Skip to main content

77. Per-Domain Task Organization

Status: Accepted Date: 2025-07-06

Context​

Given that we are storing tasks as individual files (adr://file-based-storage) within a large monorepo, we need a clear and scalable strategy for organizing these files. A single, flat directory of all task files for the entire repository would quickly become difficult to manage and would separate the tasks from their relevant context.

Decision​

The michi task files will be organized into a directory structure that mirrors the monorepo's domain structure.

  • For each domain or library that has tasks, a .tasks/ directory will be created within that domain's root directory.
  • For example, a task related to the mercury-backend application will be stored as a JSON file inside domains/mercury/backend/.tasks/.
  • A task related to the kaido-telegram library will be stored inside libs/integrations/kaido-telegram/.tasks/.

This co-locates the tasks directly with the code, FDDs, and other artifacts of the domain they belong to. The michi scripts will use the current working directory to infer the relevant domain when adding or listing tasks.

Consequences​

Positive:

  • Excellent Context Proximity: Tasks live right next to the code and documentation they relate to. This makes it incredibly easy to find relevant tasks when working within a specific part of the codebase.
  • Scalability: The system scales naturally with the monorepo. As new domains or libraries are added, they can get their own .tasks/ directory without interfering with any other part of the system.
  • Improved Scoping: It's easy for an agent or human to scope their view to only the tasks relevant to their current work (e.g., michi:ls in the mercury-backend directory will only show tasks for that domain).
  • Clear Ownership: The ownership of tasks is implicitly clear; they belong to the domain in which they are located.

Negative:

  • No Simple Global View: There is no single command to see all tasks across all domains. This requires a script that walks the file tree to find all .tasks/ directories.
  • Discovery: A developer might not know where to look for tasks if they are not familiar with this organizational scheme.

Mitigation:

  • Global List Command: A specific command (michi:ls --all) will be created that explicitly walks the repository structure to find all .tasks/ directories and aggregates the results, providing a global view when needed.
  • Documentation: This organizational structure will be a key part of the michi system's documentation, making it clear to developers how to locate tasks.
  • FDD Integration: The FDDs themselves can link directly to tasks, providing another discovery path.