The .mm/ Data Model

Monday Morning uses plain Markdown and JSON files. There is no database, no server, no proprietary format. Everything lives in the .mm/ directory and can be read, edited, and version-controlled with standard tools. In the desktop app, everything in .mm/ is collectively called artifacts — the artifact browser and entity views are windows onto these files.

Entity Hierarchy

The spec is the primary unit of work. Specs are sequenced by their dependencies, not by feature membership.

Spec (the primary unit of work)
    ├── Tasks (in spec.md's `## Tasks` section)
    │       └── Subtasks (checklist items within tasks)
    └── depends_on: [other-spec-slugs]   # what must finish first → build order

Feature (OPTIONAL — a grouping label for related specs; does not drive order)

Standalone entities:
- Issues (bugs, problems to fix)
- Notes (decisions, meeting notes, context)
- Docs (living reference documents)
- Ideas (captured for future work)

Specs

A spec describes what you are building, why, and how — and carries its own tasks. Each spec lives in its own dated folder.

Location: .mm/specs/{YYYY-MM-DD-slug}/

• Directory.mm/specs/2026-08-08-user-auth/

  • spec.md — The specification, including ## Tasks (required)
  • requirements.md — Detailed requirements (optional)
  • tasks.md — Task breakdown (optional)
  • prior-work.md — Related prior work, surfaced at shaping time
  • Directoryvisuals/ — Screenshots and design references

    • …
  • Directoryverification/ — Verification artifacts (summary.json)

    • …
  • Directorycheckpoints/ — Session checkpoints

    • …

spec.md defines the goal, requirements, scope — and tracks tasks:

---
status: planning
depends_on:
  - 2026-08-01-auth-schema
source: 'Roadmap Q3 item: secure sign-in'
---

# Specification: User Authentication

## Goal
Add email/password authentication to the web app.

## Requirements
- R1: Sign up, sign in, sign out flows
- R2: Password reset via email

## Out of Scope
- OAuth / social login (future spec)

## Tasks

#### Completed

- [x] T1: Database schema for users table (R1)

#### In Progress

- [ ] T2: Sign up API endpoint (R1)
  - [ ] T2-1: Input validation
  - [ ] T2-2: Password hashing

#### Blocked

#### Backlog

- [ ] T3: Password reset flow (R2)

Key frontmatter fields:

Field	Purpose
status	Lifecycle state. done is verification-gated (see below).
depends_on	Spec folder slugs that must finish first — the single source of truth for ordering.
source	Optional: the roadmap item, instruction, or issue this spec serves, for intent tracing.

Tasks live in spec.md

Tasks are tracked in spec.md’s ## Tasks section, under four sub-headers — #### Completed, #### In Progress, #### Blocked, #### Backlog (four hashes; three-hash headers are not recognized). Tasks use markdown checkboxes with an ID and optional time estimate:

- [ ] T1: Task title (2h)
  - [ ] T1-1: Subtask detail

Progress is calculated from top-level task checkboxes; subtasks provide detail but do not affect the percentage. Prefer mm_create with entity: "task" over hand-editing — it batches a whole task list in one write.

implementation.md is legacy

Older specs track tasks in a separate implementation.md (with two-hash ## Completed / ## In Progress / ## Backlog sections). Tools still read it for those specs, but never create it for a new spec — new specs get an empty ## Tasks section in spec.md at creation.

Requirement IDs

Each requirement carries a stable ID (R1, R2, …), and tasks cite the ID they satisfy as a trailing (R1). /mm:verify-spec keys its scorecard to these IDs and checks every requirement is covered by a task. IDs are never renumbered — append the next free one. (R0) marks scaffolding tasks that serve no single requirement.

Done is verification-gated

A spec is done only when its status: frontmatter is done, and that status is reachable only via a passing /mm:verify-spec verdict or an explicit human override in the app. All tasks checked off with no passing verdict reads as in-review everywhere — never done.

Recorded lines

A spec’s ## Recorded section is an append-only record of what agents learned or decided while working the spec. It is written only through mm_record, which requires provenance on every line — the desktop app’s session view surfaces proposed lines for the agent to append or dismiss.

Ordering: depends_on and order.json

Work is sequenced by dependencies between specs:

1. Declare prerequisites in each spec’s depends_on frontmatter (spec folder slugs).
2. Compute the build order with /mm:order-specs (or the mm_order_specs tool). It topologically sorts incomplete specs into numbered waves and writes a project-wide .mm/specs/order.json. Wave 1 has no unmet prerequisites; later waves depend on earlier ones. Each wave’s parallel flag says whether its specs can run concurrently.
3. The app shows it — the roadmap board groups specs by phase, and a spec waiting on an unfinished prerequisite is marked blocked.

Features

An optional grouping label. A feature links related specs for at-a-glance progress on the dashboard — it does not drive build order and is never required to create or sequence a spec.

Location: .mm/features/{slug}/feature.json

{
  "id": "user-management",
  "name": "User Management",
  "description": "All user-related functionality",
  "status": "in-progress",
  "priority": "high",
  "linked_specs": [
    "../specs/2026-08-08-user-auth",
    "../specs/2026-08-12-user-profiles"
  ],
  "progress": {
    "total_specs": 2,
    "completed_specs": 0,
    "percentage": 0
  }
}

Feature progress is auto-calculated from linked spec completion. linked_specs also doubles as the canonical “which specs are alike” store — the only place spec likeness is recorded, curated through a reviewed flow in the app. See Specs Workflow.

Quick Tasks (Standalone)

One-off tasks not tied to a spec — quick fixes, maintenance, ad-hoc work. Each is its own file with frontmatter; the dashboard at tasks/tasks.md links to them.

Location: .mm/tasks/{slug}-{MM-DD-YYYY}.md

---
title: Fix broken CI pipeline
type: quick
status: building
priority: high
created: 2026-08-08T10:00:00Z
updated: 2026-08-08T10:00:00Z
---

# Fix broken CI pipeline

Quick tasks use type: quick and the statuses parked, building, in-review, done. Most day-to-day work belongs in a spec’s ## Tasks instead.

Issues

Bug and problem tracking. Issues have severity levels and a resolution workflow.

Location: .mm/issues/{slug}-{MM-DD-YYYY}.md

# Login fails on Safari

**Status:** Open
**Severity:** Critical
**Created:** 2026-08-08

## Description
Users on Safari 17 see a blank screen after clicking "Sign In".

## Steps to Reproduce
1. Open Safari 17
2. Navigate to /login
3. Enter credentials and click Sign In
4. Blank screen appears

The dashboard at issues/issues.md organizes issues into Open, In Progress, and Resolved sections.

Notes

Decisions, meeting notes, and important context. Notes are temporal records that capture why choices were made.

Location: .mm/notes/{slug}-{MM-DD-YYYY}.md

# Chose JWT over session cookies

**Date:** 2026-08-08
**Category:** Architecture

## Content
We chose JWT for authentication because the API needs to serve
both the web app and mobile clients.

Docs

Living reference documents. Unlike notes (which are temporal), docs are kept current and referenced repeatedly — API guides, architecture overviews, runbooks.

Location: .mm/docs/{slug}-{MM-DD-YYYY}.md

Ideas

Captured for future work. Ideas are lightweight — a title and the raw thought — created with /mm:idea or mm_create with entity: "idea". They live in .mm/ideas/. (The old .mm/proposals/ directory is legacy; don’t put new ideas there.)

The rest of .mm/

Path	Purpose
index/	The specs index (specs.json) and the ledger/ embedding index built by mm_index — powering hybrid mm_search and mm_retrieve_prior_work.
product/	Mission, roadmap, tech stack.
standards/	Coding standards and conventions.
reviews/	Project reviews from /mm:review.
session/	Session context for agents.
config.json / config.local.json	Project configuration and machine-local overrides.

How Agents Use This Data

When an agent is dispatched, it reads .mm/ to understand:

1. What to build — specs define the goal, requirements, and scope.
2. Where things stand — task status in ## Tasks, build order in order.json.
3. What was decided and learned — notes, and each spec’s ## Recorded lines.
4. What is broken — issues highlight known problems.
5. What came before — mm_retrieve_prior_work and hybrid mm_search surface related past specs through the ledger index.

This structured context eliminates the “where was I?” problem. Instead of re-explaining your project every session, the agent reads your .mm/ directory and picks up immediately.

Note

All file formats are designed to be human-readable and human-editable. You can create and modify any entity with a text editor — agents and MCP tools are a convenience, not a requirement.

Next Steps

• Your First Workflow — Put this all together: create a spec, add tasks, complete work.
• MCP Tools Reference — Browse the universal verbs and core catalog agents use to work with this data.