Skip to main content

75. File-Based Task Storage

Status: Accepted Date: 2025-07-06

Context​

Given that we are using Git as our transactional engine (adr://git-as-atomic-engine), we need a storage format for our tasks that is simple, human-readable, and works well with Git and standard command-line tools. Using a binary format or a complex database file would make diffs unreadable and require specialized tools to inspect or manipulate the data.

Decision​

All michi tasks will be stored as individual JSON files on the filesystem.

  • Each task will have its own file, named with a unique identifier (e.g., <uuid>.json).
  • The content of the file will be a simple JSON object representing the task's properties (e.g., title, status, fddLink).
  • These JSON files will be organized into directories that mirror the application's structure (adr://per-domain-organization).
  • To prevent the AI agent from accidentally editing these files directly (and bypassing the atomic Git-based scripts), the root task directories (e.g., domains/*/.tasks/) will be added to .cursorignore.

Consequences​

Positive:

  • Human-Readable & Editable: JSON is easy for both humans and machines to read and write. A developer can easily inspect a task file with cat or edit it with vim if manual intervention is needed.
  • Excellent Diffing: Git provides excellent, line-by-line diffs for text-based formats like JSON, making changes easy to review in commit history.
  • Tool-Friendly: The format is trivial to parse and manipulate with ubiquitous command-line tools like jq, which simplifies scripting.
  • Decentralized & Unstructured: No schema migrations are needed. Adding a new property to tasks is as simple as having the script write a new key-value pair to the JSON file.

Negative:

  • Less Efficient for Complex Queries: Querying across many tasks (e.g., "find all high-priority tasks") requires reading and parsing multiple files from the disk, which is less efficient than a query to an indexed database.
  • Potential for Inconsistency: Without a database schema, there is no enforcement that all task files have the same structure. A buggy script could write malformed JSON or omit required fields.

Mitigation:

  • Single-Agent Focus: The system is not designed for complex, ad-hoc querying. Its primary purpose is to allow an agent to manage a specific list of tasks. The shell scripts will provide the necessary "query" functionality (e.g., michi:ls).
  • Schema Validation in Scripts: The shell scripts that interact with the task files will be responsible for validating the JSON structure. Any malformed file can be flagged as an error.
  • Taskwarrior Compatibility: The JSON structure will be designed to be compatible with Taskwarrior (adr://taskwarrior-compatibility), providing a well-defined and battle-tested schema to follow.