Skip to main content

78. Taskwarrior Compatibility for Human Interface

Status: Accepted Date: 2025-07-06

Context​

While the michi system is primarily designed for an AI agent interacting via shell scripts (adr://shell-script-interface), human developers also need a convenient way to view and manage these same tasks. Building a custom human-facing CLI from scratch would be redundant if we can leverage existing, battle-tested tools. Taskwarrior is a powerful, popular, and highly-regarded open-source command-line task manager.

Decision​

The JSON format used for michi task files (adr://file-based-storage) will be designed to be directly compatible with Taskwarrior's import format.

This means that the key names in our task JSON files will align with Taskwarrior's standard fields (e.g., uuid, description, status, entry, priority, tags).

This allows a human developer to use the standard task command-line tool to interact with the tasks. They can configure Taskwarrior to use the local .tasks/ directory as its data source, and then run commands like task list, task next, or task add to view and manage tasks in a familiar, powerful way. The michi scripts will be responsible for generating JSON that Taskwarrior can understand.

Consequences​

Positive:

  • Leverages Powerful Existing Tools: We get a feature-rich, human-friendly CLI for free. Developers can use Taskwarrior's advanced filtering, reporting, and visualization capabilities without us having to build any of it.
  • Reduces Development Effort: We don't need to build and maintain a separate CLI for human interaction.
  • Provides a Well-Defined Schema: Adhering to the Taskwarrior format gives us a battle-tested and well-documented "schema" for our task objects.
  • Smooth Human-AI Handoff: A human can easily review, prioritize, or even add tasks to the list that the AI agent will then pick up, as they are both operating on the same underlying data files.

Negative:

  • Format Constraint: We are constrained by the data model and format of Taskwarrior. If we need to store a piece of information that doesn't fit neatly into Taskwarrior's model, we might have to use workarounds (like stuffing it into annotations or user-defined attributes).
  • Configuration Step for Humans: Developers will need to perform a one-time configuration of their local Taskwarrior setup to point it to the correct data directory.

Mitigation:

  • Flexible Schema: Taskwarrior's schema is quite flexible and supports user-defined attributes (UDAs), which provides an escape hatch for any custom data we might need to store.
  • Automated Configuration: We will provide a simple script to automatically configure a developer's Taskwarrior installation to work with the michi system, making the setup process painless.
  • Focus on Core Fields: For agent-driven workflows, we will stick to the core, standard Taskwarrior fields, ensuring maximum compatibility.