Design Philosophy

Taskulus is built on a set of core principles that prioritize developer experience, transparency, and longevity.

Why Taskulus Exists

Game-changing technology for the age of AI agents.

The Sleep Factor

The motivation for Taskulus came from a simple need: to offload mental context. When you are juggling dozens of open loops—chat sessions, pending tasks, architectural decisions—you need a place to put them that doesn't require "logging in" or managing infrastructure.

Taskulus allows you (and your AI agents) to dump context immediately into the repository. It's the difference between keeping 15 plates spinning in your head and putting them on a shelf.

Inspiration & Lineage

Standing on the shoulders of giants.

A Spiritual Successor to Beads

This project was inspired by Beads and is intended as a spiritual successor that embraces the elegant domain-specific cognitive framework it pioneered. We are deeply grateful to the Beads author and community for proving the concept so well.

Taskulus represents the next generation of this idea, improved for the era of AI agents:

  • Thinner layer over Git: We removed the secondary SQLite database to eliminate synchronization complexity.
  • Git-aligned storage: Separate files for separate tasks mean no merge conflicts when agents work in parallel.
  • Focused Cognitive Model: We stripped away 100+ unused attributes to focus on the core cognitive framework, reducing context pollution for AI models.
  • Standard Nomenclature: We use standard terms (Epics, Tasks) to leverage the massive pre-training AI models already have on these concepts.

Core Principles

The fundamental rules that guide the development of the Taskulus system.

1. Files are the database

There is no hidden SQLite file, no background daemon, and no remote API. The state of your project is strictly defined by the JSON files in your repository. Each command scans those files directly—the files are the truth.

2. One File Per Issue

Other systems store everything in a single JSONL file. This guarantees merge conflicts when two people (or agents) work on different tasks simultaneously. Taskulus splits every issue into its own file, letting Git handle the merging naturally.

3. Helpful Cognitive Model

The task model should unburden your mind, not add to it. We stripped away 100+ unused attributes to focus on a core, elegant framework (Status, Priority, Dependencies). This helps AI agents focus on solving problems, not navigating the tool.

4. Agent-Native

Taskulus is basically Jira + Confluence for agents. The CLI allows agents to read the current state of the world, and the Wiki engine allows them to read dynamic summaries of initiatives. It is designed to be the memory bank for your AI workforce.

5. Git-Native Scoping

We don't need complex "roles" to handle private tasks. Just use .gitignore. Taskulus respects your directory structure: run it at the root to see everything, or in a subfolder to focus on that module. It leverages the tools you already use.

Architecture

How Taskulus works under the hood.

No Friction

Git hooks should help you, not block you. Taskulus removes the concept of "syncing" entirely. There is no secondary database to maintain, so you are never blocked from pushing your code.

The Wiki Engine

The `wiki` command renders Markdown templates using the Jinja2 engine. It injects a `project` context object that gives you access to the entire issue graph. This allows you to write "living documents" that always reflect the latest status.