Markdown Task Management

Relevant source files

The following files were used as context for generating this wiki page:

• cli/src/tasks/markdown.ts
• cli/src/tasks/markdown-folder.ts
• morty.sh
• README.md
• cli/src/cli/args.ts
• cli/src/execution/parallel.ts

Markdown Task Management is a core feature of Morty that allows users to define project requirements and tasks using standard Markdown syntax. The system interprets GitHub-flavored checkboxes (- [ ]) as actionable items for AI agents to process. This enables a "PRD-driven" workflow where the AI iterates through a Product Requirements Document (PRD) until all tasks are marked as complete.

The system supports both single-file PRDs and folder-based task management for larger projects. In folder mode, Morty aggregates tasks from all .md files within a specified directory, providing a scalable way to manage complex development cycles.

Sources: README.md:32-35, cli/src/tasks/markdown.ts:5-7, cli/src/tasks/markdown-folder.ts:6-8

Task Detection and Parsing

Morty identifies tasks by scanning Markdown files for specific line patterns. The primary identifier for an incomplete task is the - [ ] prefix, while completed tasks are identified by - [x].

Regex-Based Extraction

The system uses regular expressions to parse these lines and extract the task description. For a single file, the line number is used as a unique identifier to ensure that when a task is completed, only the specific line in the source file is modified.

// Match incomplete tasks
const incompleteMatch = line.match(/^- \[ \] (.+)$/);
if (incompleteMatch) {
    tasks.push({
        id: String(i + 1), // Line number as ID
        title: incompleteMatch[1].trim(),
        completed: false,
    });
}

Sources: cli/src/tasks/markdown.ts:25-33, morty.sh:542-550

Folder-Based Aggregation

When pointing to a directory, the system scans for all files ending in .md. Task IDs in this mode are composite strings containing the filename and the line number (e.g., feature.md:12) to allow precise updates across multiple files.

Sources: cli/src/tasks/markdown-folder.ts:24-34, cli/src/tasks/markdown-folder.ts:55-58

Core Components and Architecture

The Markdown task system is built on a provider pattern, where different classes handle specific storage formats while adhering to a common interface.

Component	Description	File Path
MarkdownTaskSource	Handles task extraction and updates for a single .md file.	cli/src/tasks/markdown.ts
MarkdownFolderTaskSource	Aggregates tasks from multiple .md files within a directory.	cli/src/tasks/markdown-folder.ts
get_tasks_markdown	Bash utility function to extract pending tasks using grep.	morty.sh:542-544
mark_task_complete	Logic to replace - [ ] with - [x] in the source file.	morty.sh:558-568

Logic Flow for Task Processing

The following diagram illustrates how the system transitions from reading a Markdown PRD to executing a task and updating the source file.

State Persistence and Updates

Morty ensures that the PRD remains the "source of truth." When an AI agent completes a task, the system performs an in-place modification of the Markdown file.

Task Completion Logic

In the Bash implementation, sed is utilized for precise line replacement, ensuring that special characters in the task description are escaped to prevent command injection or regex failures.

mark_task_complete_markdown() {
  local task=$1
  local escaped_task
  escaped_task=$(printf '%s\n' "$task" | sed 's/[[\.*^$/]/\\&/g')
  sed -i.bak "s/^- \[ \] ${escaped_task}/- [x] ${escaped_task}/" "$PRD_FILE"
  rm -f "${PRD_FILE}.bak"
}

Sources: morty.sh:558-568

In the TypeScript CLI, the file is read into memory, the specific line index is modified, and the entire content is written back to disk.
Sources: cli/src/tasks/markdown.ts:47-54, cli/src/tasks/markdown-folder.ts:86-92

Parallel Execution Handling

When running in parallel mode (--parallel), the system clones the PRD into isolated worktrees. However, the completion of tasks is coordinated such that the main task source is updated only after an agent successfully commits changes. This prevents multiple agents from attempting to work on the same task simultaneously.
Sources: cli/src/execution/parallel.ts:85-100, README.md:120-130

User Configuration

Users can specify the PRD source via CLI flags. The system also attempts to auto-detect PRD.md in the current directory if no source is provided.

Flag	Argument	Description
--prd	<path>	Path to a .md file or a directory containing Markdown files.
--yaml	<file>	Alternative task source using YAML format.
--github	<repo>	Alternative task source using GitHub Issues.

Sources: cli/src/cli/args.ts:39-44, cli/src/cli/args.ts:98-112

Summary

Markdown Task Management provides a human-readable and AI-parseable interface for autonomous development. By leveraging standard checkbox syntax, Morty allows developers to define complex workflows in simple documents, which the system then executes, tracks, and updates automatically across single or multiple files.