feat: support or Use .md Files with YAML Frontmatter Instead of JSON

[orakemu]

Motivation

JSON is machine-friendly but hard to read and edit by hand. Markdown with YAML frontmatter improves human readability and allows easy manual editing, version control, and documentation.

Proposed Solution

• Store all PRDs, tasks, and subtasks as Markdown files with YAML metadata.
• Use js-yaml and a Markdown parser for reading/writing data.
• Provide migration scripts for converting existing JSON files to the new format.

High-Level Workflow

1. Define a YAML metadata schema for tasks, subtasks, and PRDs.
2. Refactor storage logic to read/write .md files with YAML frontmatter.
3. Update all file access functions to use the new format.
4. Test migration from JSON to Markdown/YAML.
5. Update documentation and usage examples.

Key Elements

• YAML metadata: status, project, type, priority, etc.
• Markdown for human-editable content
• Migration script for legacy JSON
• Updates to file read/write logic

Example Workflow

$ task-master new-task --title "Implement Login API" --project Authentication
→ Created tasks/implement-login-api.md

prd example

---
title: "User Authentication Feature"
project: "Authentication"
type: "prd"
status: "inprogress"
priority: "high"
created: "2025-06-08"
owner: "orakemu"
---

# User Authentication PRD

This feature adds user registration, login, and session management.

## Goals
- Secure authentication
- Email verification

## Deliverables
- API endpoints for sign up and login
- Unit tests

task example

---
title: "Implement Login API"
project: "Authentication"
type: "task"
status: "backlog"
priority: "medium"
created: "2025-06-08"
assignee: "orakemu"
parent: "User Authentication Feature"
---

# Task: Implement Login API

Create the `/api/login` endpoint.  
Validate credentials, generate JWT, and return it to the client.

subtask example

---
title: "Add JWT Generation"
project: "Authentication"
type: "subtask"
status: "backlog"
priority: "medium"
created: "2025-06-08"
assignee: "orakemu"
parent: "Implement Login API"
---

# Subtask: Add JWT Generation

- Use the `jsonwebtoken` library.
- Store secret securely in environment variables.

Implementation Considerations

• Migration complexity for existing users
• Ensuring consistent parsing/serialization
• File naming and collision handling

Out of Scope (Future Considerations)

• UI for direct YAML/Markdown editing
• Support for additional markup formats

[eyaltoledano]

The tasks are meant for the machine, not for the human. You're missing the point of the toolkit if you're manually adjusting files -- I understand the perspectiev that you might want to quickly add small changes here and there, and there's a use case for that, but generally speaking you want to avoid spending/wasting time manually adjusting context files when AI can be prompted to do that across different dimensions (i recognize this is not useful for tiny adjustments).

I've been thinking of deprecating the task files actually. The tasks.json file is plenty, and the individual task files are really just a final fallback in case the CLI/MCP are both unavailable so you can still pass the agent context through the individual task files.

All that said, I don't see why we couldn't add a config flag to define the file extension/rendering method for the task files. Assuming we keep the task files.

What is the use case for human readability? When do you find yourself consuming the task through the task file itself instead of through the CLI or MCP?