YAML Task Definition

Relevant source files

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

• cli/src/tasks/yaml.ts
• cli/src/tasks/types.ts
• morty.sh
• cli/src/execution/parallel.ts
• cli/src/config/types.ts
• README.md

YAML Task Definition is a structured method for defining and managing coding tasks within Morty. Unlike simple Markdown checklists, the YAML format allows for advanced metadata, such as parallel execution groups, which enables Morty to orchestrate complex workflows across multiple AI agents simultaneously.

This feature is primarily used in PRD mode, where Morty reads a designated task file and executes the defined steps until the project requirements are met. It serves as a core component of the "Autonomous AI Coding Loop," providing a machine-readable schema for task status, descriptions, and dependency grouping.
Sources: morty.sh:16-19, README.md:104-114

Data Structure and Schema

The YAML task definition follows a specific schema consisting of a top-level tasks key containing an array of task objects. Each task object defines the title, completion status, and optional grouping metadata.

Task Object Fields

Field	Type	Description
title	String	A descriptive name for the task. Used as the unique identifier.
completed	Boolean	Tracks whether the task has been finished. Defaults to false.
parallel_group	Number	Optional. Tasks with the same group number are executed concurrently.
description	String	Optional. Provides additional context for the AI agent.

Sources: cli/src/tasks/yaml.ts:6-14, cli/src/tasks/yaml.ts:46-54, README.md:144-153

YAML Example Definition

tasks:
  - title: "Implement User Authentication"
    completed: false
    parallel_group: 1
    description: "Create login/register logic with JWT"
  - title: "Design Dashboard UI"
    completed: false
    parallel_group: 1
  - title: "Add Auth Guard to Dashboard"
    completed: false
    parallel_group: 2

Sources: cli/src/tasks/yaml.ts:20-25, README.md:144-153

Task Management Logic

The YamlTaskSource class implements the TaskSource interface to handle file I/O and task state transitions. It uses the yaml library to parse and stringify the task file.

Core Architecture

The logic involves reading the entire file into memory, performing operations on the task array, and writing the updated content back to the source file to maintain state.
Sources: cli/src/tasks/yaml.ts:26-44

Sequence: Task Completion Flow

The following diagram illustrates how the system updates a YAML task once an AI agent finishes its work.

Parallel Execution and Grouping

One of the primary advantages of the YAML definition is the parallel_group attribute. This allows Morty to manage task dependencies.

1. Sequential Batches: Morty identifies the next available parallel_group.
2. Concurrency: All tasks within that specific group are spawned as separate AI agents, each running in an isolated git worktree.
3. Synchronization: Morty waits for all tasks in the current group to finish (or fail) before moving to the next group.
4. Integration: After a group completes, Morty merges the individual agent branches into an integration branch so the subsequent group has access to the completed work.

Sources: morty.sh:1003-1015, cli/src/execution/parallel.ts:241-255, README.md:144-153

Execution Flow Logic

CLI Integration

To use the YAML task definition, users must specify the --yaml flag followed by the path to the file. This overrides the default Markdown (PRD.md) source.

Command	Description
morty --yaml tasks.yaml	Starts Morty using the specified YAML file as the task source.
morty --yaml tasks.yaml --parallel	Executes grouped YAML tasks in parallel.

Sources: morty.sh:511-513, cli/src/cli/args.ts:98-101, README.md:104-107

Summary

The YAML Task Definition provides a robust, machine-readable framework for complex project automation within Morty. By supporting metadata like parallel_group, it enables the system to transition from simple sequential execution to sophisticated, dependency-aware parallel processing. This ensures that AI agents work in a logical order while maximizing efficiency through concurrent execution where possible.
Sources: cli/src/tasks/yaml.ts:1-100, cli/src/execution/parallel.ts:241-255