Projects

Create Project


mdp project create -p <path>

Create a new markdown project and register it.

Flag	Short	Default	Description
`--force`	`-F`	`false`	Overwrite existing `.mdp/` directory
`--preset <name>`		`"software"`	Project preset: `software`, `marketing`, `design`, `product`, `generic`
`--with-templates`		`true`	Create default template files
`--no-with-templates`			Skip creating template files
`--issue-prefix <prefix>`		`"ISS"`	Prefix for issue IDs
`--milestone-prefix <prefix>`		`"M"`	Prefix for milestone IDs
`--tags <tags>`			Comma-separated tags for grouping
`--title <title>`		directory name	Project title
`--name <name>`			Alias for `--title`
`--description <description>`			One-line project description
`--instructions <instructions>`			Free-text guidance for LLMs and collaborators

Behavior:

Creates .mdp/ directory with settings.json (schema config) and project.md (project identity)
Creates issues/, milestones/, docs/, templates/ subdirectories
Preset is resolved from built-in and custom presets (defined in ~/.mdp/settings.json), then CLI flags override on top
Registers the project in ~/.mdp/settings.json
Fails with exit code 1 if .mdp/ already exists (unless --force)


{
  "ok": true,
  "data": {
    "projectPath": "/home/user/my-project",
    "created": {
      "settingsFile": ".mdp/settings.json",
      "projectFile": ".mdp/project.md",
      "directories": [".mdp/issues", ".mdp/milestones", ".mdp/docs", ".mdp/templates"],
      "templates": [".mdp/templates/issue-template.md", ".mdp/templates/milestone-template.md"]
    }
  }
}

After creation, the directory looks like:


.mdp/
├── settings.json
├── project.md
├── issues/
├── milestones/
├── docs/
└── templates/
    ├── issue-template.md
    └── milestone-template.md

Get Project


mdp project get -p <path>

Get project identity, health, log, and body content from .mdp/project.md.

Flag	Default	Description
`--include-content`	`true`	Include markdown body in output
`--no-include-content`		Exclude markdown body from output


{
  "ok": true,
  "data": {
    "title": "My Project",
    "description": "A project description",
    "instructions": null,
    "health": "on-track",
    "log": [
      {
        "timestamp": "2025-01-15T10:00:00.000Z",
        "author": "cli",
        "body": "Project kickoff",
        "health": "on-track"
      }
    ],
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z",
    "filePath": ".mdp/project.md",
    "content": "## Overview\n\n..."
  }
}

Add Project


mdp project add <path>

Flag	Default	Description
`--tags <tags>`		Comma-separated tags for grouping

List Projects


mdp project list

List all registered projects.

Flag	Default	Description
`--tag <tag>`		Filter projects by tag


{
  "ok": true,
  "data": {
    "projects": [
      {
        "path": "/home/user/project-a",
        "tags": ["work"]
      }
    ],
    "total": 1,
    "tagDescriptions": {
      "work": "Acme Corp — B2B SaaS for supply chain management"
    }
  }
}

Remove Project


mdp project remove <path>

Remove a registered project path. Does not delete any files — only removes the project from the registry in ~/.mdp/settings.json.

Tag Project


mdp project tag <path> --add <tags>

Add or remove tags from a registered project. Tags added via --add are auto-created in the global tag list (with an empty description) if they don’t already exist.

Flag	Description
`--add <tags>`	Comma-separated tags to add (auto-creates missing tags)
`--remove <tags>`	Comma-separated tags to remove

Show Settings


mdp project settings -p <path>

Display the project schema settings from .mdp/settings.json.


{
  "ok": true,
  "data": {
    "projectPath": "/home/user/my-project",
    "settingsFile": "/home/user/my-project/.mdp/settings.json",
    "config": { ... }
  }
}

Show Stats


mdp project stats -p <path>

Show project statistics.


{
  "ok": true,
  "data": {
    "projectPath": "/home/user/my-project",
    "projectName": "my-project",
    "totalIssues": 24,
    "statusCounts": { "Backlog": 10, "In Progress": 5, "Done": 9 },
    "priorityCounts": { "High": 3, "Medium": 12, "Low": 9 },
    "typeCounts": { "task": 14, "bug": 5, "feature": 3, "chore": 2, "spike": 0 },
    "labelCounts": { "bug": 5, "enhancement": 12 },
    "createdThisMonth": 8,
    "updatedThisMonth": 15
  }
}

Project Log

Manage log entries on the project. Supports optional health tracking (on-track, at-risk, off-track).


mdp project log add -p <path> -b "message" [--author <name>] [--health on-track|at-risk|off-track] [--dry-run]
mdp project log list -p <path>
mdp project log get -p <path> --index <n>
mdp project log update -p <path> --index <n> [-b <body>] [--author <name>] [--health <health>] [--dry-run]
mdp project log delete -p <path> --index <n> [--dry-run]

When --health is provided on add or update, the health value is stored both in the log entry AND propagated to the top-level health field in project.md frontmatter.

Fix Project


mdp project fix -p <path>

Fix folder names to match frontmatter data.

Flag	Default	Description
`--dry-run`	`false`	Preview changes without applying them

Behavior:

Renames folders to match {id}-{slug} convention based on frontmatter title

Before fix:


.mdp/issues/
└── ISS-5-old-name/
    └── ISS-5-old-name.md        # frontmatter title: "Fix login bug"

After fix:


.mdp/issues/
└── ISS-5-fix-login-bug/
    └── ISS-5-fix-login-bug.md


{
  "ok": true,
  "data": {
    "actions": [
      {
        "type": "rename",
        "entity": "issue",
        "id": "ISS-5",
        "from": ".mdp/issues/ISS-5-old-name",
        "to": ".mdp/issues/ISS-5-fix-login-bug"
      }
    ],
    "total": 1
  }
}