Imagine working on a project where your entire roadmap, task list, and progress are stored in plain JSON files right on your disk. No cloud, no database, no login required. That’s the bold idea behind Threlmark’s ‘disk is the contract’ architecture.

It’s a different way of thinking about data — one that prioritizes local storage as the ultimate authority. This shift makes your workflow more resilient, portable, and compatible with AI agents that can read, write, and even move your work forward without fuss.

The goal? To create a system where your data stays with you, and tools can join in without permission or lock-in. Let’s unpack how this works and why it’s a game-changer.

Key Takeaways

• Your project data lives in plain JSON files, making it easy to back up, migrate, and join with other tools.
• One file per item prevents conflicts and simplifies concurrent updates, boosting reliability.
• Directory structure acts as a formal contract, ensuring transparency and interoperability.
• Atomic file writes and normalization safeguard against corruption and compatibility issues.
• External tools and AI agents can read, write, and move work seamlessly by following the file-based contract.

How Threlmark Keeps Your Data Safe and Portable

Threlmark treats your disk as the single source of truth. Every file — from project configs to individual task cards — is a plain JSON file. This means you can open, edit, or move your data with any tool that understands JSON.

For example, your roadmap lives in items/ as individual files, each representing a task. You can back up your entire project by copying a folder or sync it across devices with Dropbox or rsync. No vendor lock-in, no proprietary formats.

This design makes your data highly portable and easy to recover. If your disk crashes, you just restore the files. If you want to switch tools, just start reading and writing those same files with your favorite editor or script.

Why One File Per Item Wins Over Big JSON Files

Many projects use a big JSON array to store all tasks. It’s simple, but it’s a nightmare for concurrency. Every change requires rewriting the whole list, risking conflicts and clobbers.

Threlmark avoids this by using one file per item — items/.json. When you change a task, you only update that one file. It’s atomic, collision-proof, and easy to sync.

This setup means external tools can update individual cards without messing up the whole project. Plus, the system self-heals: if a card disappears from the directory but is still referenced in the lane list, it’s just ignored until it’s back.

How Threlmark’s Layout Ensures Everything Fits and Works

The directory structure isn’t just for looks. It’s a contract that guarantees every artifact is inspectable and interoperable.

At the root, you find threlmark.json (the manifest), links.json (dependencies), and folders for projects, shared items, suggestions, handoffs, reports, and archives.

This setup allows any tool — whether a CLI script or an AI agent — to access the full state by just reading files. No server needed. Everything can be version-controlled, diffed, and migrated easily.

Making File Writes Safe Without a Database

Using files for data storage sounds risky — what if two programs write at once? Threlmark solves this with atomic writes. Each update writes to a temp file, then renames it. Because rename is atomic on most filesystems, you never get partial data.

For example, updating a task involves writing a new file with a unique temp name, then renaming it over the old one. This guarantees data consistency even if your system crashes mid-write.

Plus, it uses read-merge-write with tolerant normalization, so older tools can handle new fields gracefully. This forward compatibility keeps your data safe as the system evolves.

How the Board Self-Heals and Keeps Your Workflow Smooth

The lane ordering, stored in board.json, is designed to stay consistent. But what if a task gets deleted or moved? Threlmark’s clever trick is self-healing: every time you read board.json, it reconciles against actual items.

So if an item is missing from items/ but still listed on the board, it’s ignored. Conversely, new items get added automatically. This makes your workspace resilient and reduces manual cleanup.

Imagine a scenario: you archive a project, but its cards linger in the lane list. When the board loads, it automatically cleans up the dead references, keeping your workflow clean and current.

How External Tools and AI Agents Play Nice with Files

Threlmark opens the door for outside tools to participate without asking permission. External scripts or AI agents can read from suggestions/ for new ideas, write directly to handoffs/ to push work forward, and check reports/ to see what’s done.

For instance, an AI agent can scan suggestions, pick a task, update its status, and move it to done — all by just reading and writing files. No API calls or special permissions needed.

This open approach makes automation natural and safe. You can even run your own scripts or AI models locally, knowing they’re working within the exact same contract.

What This Means for Your Projects and Workflow

Adopting Threlmark’s ‘disk is the contract’ philosophy transforms how you manage projects. Your data becomes portable, conflict-resistant, and ready for automation. Offline work? No problem.

It’s perfect for solo developers, small teams, or any project where resilience and flexibility matter. Instead of locking into a cloud service, you own the entire system — just files and scripts.

Plus, the architecture encourages experimentation: try new tools, scripts, or AI integrations without rewriting your entire setup. The system adapts to your needs, not the other way around.

Frequently Asked Questions

How does this architecture handle conflicts when multiple tools update files at the same time?

Threlmark uses atomic writes—each update replaces a file in one operation—so conflicts are avoided without locks. For complex conflicts, strategies like CRDTs or manual resolution can be integrated.

Can I switch from a cloud-based system to this local-first setup easily?

Absolutely. Since all data lives in plain JSON files, migrating is as simple as copying your files to a new location or syncing them with your preferred tools, with no vendor lock-in.

What if I want to add custom fields or new features later?

The system’s design preserves unknown fields during read-write cycles, so you can extend your data schema without breaking existing tools or losing compatibility.

Is this approach suitable for team collaboration?

Yes, especially in small teams or solo projects. Files can be shared via sync tools, and conflict resolution strategies can be built-in, making distributed work straightforward.

Are there any downsides or limitations?

It requires discipline in managing files and handling synchronization, especially at scale. Also, complex conflict scenarios might need custom resolution logic, but overall, it offers a resilient, lock-free workflow.

Conclusion

Threlmark’s ‘disk is the contract’ isn’t just a technical choice — it’s a philosophy that puts data sovereignty and flexibility at the forefront. Your projects become resilient, portable, and ready for automation.

Think of your data as a living garden in plain files. Tending it with care means fewer crashes, more control, and smarter workflows. Why settle for lock-in when your work can be this free?