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.

Entity Hierarchy

Feature (groups related specs — optional)
    └── Spec (the unit of work)
            └── Tasks (tracked in implementation.md)
                    └── Subtasks (checklist items within tasks)

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

Specs

The core unit of work. A spec describes what you are building, why, and how. Each spec lives in its own dated folder.

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

Directory.mm/specs/2026-03-31-user-auth/
- spec.md — The specification (required)
- implementation.md — Task tracking (required for progress)
- requirements.md — Detailed requirements (optional)
- tasks.md — Mirror of implementation.md (optional)

spec.md defines the goal, requirements, and scope:

# Specification: User Authentication

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

## Requirements
- Sign up, sign in, sign out flows
- Password reset via email
- Session management with JWT

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

implementation.md tracks tasks and progress:

# User Authentication - Implementation

## Completed
- [x] T1: Database schema for users table [S]

## In Progress
- [ ] T2: Sign up API endpoint [M]
  - [ ] T2-1: Input validation
  - [ ] T2-2: Password hashing

## Backlog
- [ ] T3: Sign in endpoint [M]
- [ ] T4: Password reset flow [L]

Progress is calculated from top-level task checkboxes. Subtasks (indented items) provide detail but do not affect the percentage.

Section headers

Implementation files use these sections:

Section	Purpose
`## Completed`	Done tasks (counted toward progress)
`## In Progress`	Actively being worked on
`## Blocked`	Waiting on something external
`## Backlog`	Not yet started
`## Archive`	Old completed tasks (not counted in progress)

Task format

Tasks use markdown checkboxes with an ID and optional size annotation:

- [ ] T1: Task title [M]
  - [ ] T1-1: Subtask detail
  - [x] T1-2: Completed subtask

Size annotations: [XS], [S], [M], [L], [XL] indicate relative effort.

Features

Optional grouping of related specs. A feature links multiple specs together for aggregate progress tracking.

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-03-31-user-auth",
    "../specs/2026-04-05-user-profiles"
  ],
  "progress": {
    "total_specs": 2,
    "completed_specs": 0,
    "percentage": 0
  }
}

Feature progress is auto-calculated from linked spec completion.

Tasks (Standalone)

One-off tasks not tied to a spec. Use these for quick fixes, maintenance, or ad-hoc work.

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

Each standalone task is its own file with frontmatter:

---
title: Fix broken CI pipeline
category: DevOps
priority: High
status: pending
created: 2026-03-31
---

# Fix broken CI pipeline

## Description
The nightly build has been failing since the Node.js upgrade.

## Checklist
- [ ] Update Node version in CI config
- [ ] Fix deprecated API calls
- [ ] Verify green build

The dashboard at tasks/tasks.md links to individual task files.

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-03-31

## 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-03-31
**Category:** Architecture

## Content
We chose JWT for authentication because the API needs to serve
both the web app and mobile clients. Session cookies would
require additional CORS handling for the mobile app.

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

How AI Agents Use This Data

When you start an AI coding session, agents read the .mm/ directory to understand:

What you are building — specs define the goal and requirements.
Where you left off — task completion status in implementation files.
What decisions were made — notes capture architectural reasoning.
What is broken — issues highlight known problems.

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.

Next Steps

Your First Workflow — Put this all together by creating a spec, adding tasks, and completing work.
MCP Tools Reference — Browse the 54+ tools AI agents use to interact with project state.