Working name:
tda(a pun on trouble de l'attention / to-do app). A keyboard-first tool to capture, organize, and refine ideas and tasks — linearly and as graphs/trees — for both humans and AI agents.
This document is written to be handed directly to Claude Code. It is opinionated: every place where I made a call that you might disagree with is marked [DECISION] with a one-line rationale, and the genuinely open ones are collected in §13 Open questions. Override freely.
A fast capture-and-organize tool for people (and agents) who think in bursts. The core loop:
- Dump ideas/tasks at the speed of typing, no friction.
- Organize them into hierarchies and lists, reorder by priority, tag.
- Refine drafts until they are claimable units of work.
- Delegate to a human or an AI agent, who can claim and execute with full parent context.
The same domain is reachable through a CLI, a TUI, an HTTP API, and (later) a GUI and an MCP server for agents — all sharing one core and one navigation model.
First success criterion (dogfooding): the app is "done enough" the moment it can store this roadmap as its own task tree and export it back to Markdown. That is Milestone M3.
Goals
- Keyboard-only batch task creation; sub-second navigation.
- Arbitrary-depth hierarchy, and the same task reachable from multiple trees/lists (a DAG, not a single tree).
- Per-view ordering that doubles as priority, manually reorderable.
- Tags, multi-assignment (0–n, humans or agents), claiming, draft lifecycle.
- Aggregation up the hierarchy (status/progress, time spent, ETA, due date).
- Markdown/JSON import & export of any list or branch.
- A clean hexagonal core with no I/O, fully unit-tested before any adapter exists.
Non-goals (for v1)
- Real-time multi-user sync / CRDT collaboration. (Single-user, single-machine first.)
- Mobile apps.
- Account system / auth. (API is local/trusted first; see §13.)
- gRPC. [DECISION] Start HTTP+JSON only — universally consumable by agents and tooling; gRPC adds build/codegen cost with no v1 payoff. Revisit if streaming/perf demands it.
- Rich text beyond plain Markdown notes. [DECISION] Attachments (link or actual file/image bytes) are, however, in scope — see
Attachments/BlobStorein §3/§7. Superseded the earlier "no attachments" non-goal to support importing tasks (e.g. from Super Productivity) that carry file/image references.
| Term | Meaning |
|---|---|
| Task | The atomic unit: a stable identity (id + timestamps) that carries a set of capabilities rather than a fixed field list. Required: Title, Status. Optional capabilities attach à la carte. |
| Capability | A composable unit of data + behaviour attached to a task: Status, Notes (Markdown), Schedule (due date, optionally with time-of-day), Estimate (ETA), TimeSpent, TimeLog (per-day breakdown), Tags (also settable via the #tag title shorthand, FR-33), Assignment, Recurrence, IssueRef, Workspace, Attachments, Archived. A capability may define (a) data, (b) an aggregation (how it rolls up a subtree), and (c) guards (which commands it allows/denies). Tasks differ by which capabilities they hold — composition, not an OOP god-struct. Adding a capability touches nothing existing. |
| Status | A required capability. Values: draft, todo, wip, paused, done (see §8) — [DECISION] any value may be set to any other, freely, no transition guard. Aggregates to subtree progress. blocked is not a stored value — it's derived from unmet blocks deps. |
| Assignment | An optional capability: 0–n assignees (Person or Agent). Its presence changes Claim semantics (see §8): absent/empty ⇒ anyone may claim; present ⇒ only a listed assignee may claim. Also settable via the @name title shorthand (FR-32): typing @name in a title adds name as an assignee and strips the mention from the stored title. |
| Recurrence | An optional capability: a repeat rule (daily/weekly-by-weekday/monthly). [DECISION] No per-occurrence task spawning — a recurring task resets in place: completing it (SetStatus(done)) recomputes its Schedule from the rule and its own current due date, and flips Status back to todo, instead of staying done. A task with no Schedule can't meaningfully recur, so it just completes normally. |
| IssueRef | An optional capability: a static {provider, id, url} reference to an external issue tracker (e.g. a GitHub/Jira issue) — no live sync, no computed URL. Mainly populated by imports. |
| Workspace | An optional capability (FR-35): {name, path?} binding a task — and, via nearest-ancestor lookup, its subtree — to a project folder/repo. Set on a project's root task by convention (tda ws init). name is the stable cross-machine identity; path is only a default local folder — per-machine overrides live in the local config's [workspaces] table (name = "/local/path"), never in the store, so a shared database stays portable. --here on queries resolves cwd → the workspace root whose effective path contains it (deepest match wins). |
| Attachments | An optional capability: a list of {id, kind (link/file/image), title, url, blob, mime}. link never has a blob; file/image may reference actual bytes stored via the BlobStore port (content-addressed) or just carry a source url/path when bytes aren't available (e.g. an import that only has metadata). |
| Archived | An optional, presence-only capability, orthogonal to Status (a task can be done and archived, or archived without being done) — resolves §13 Q4: archived tasks stay in the store (not moved to a separate structure) and are hidden from default views (what-next, due-today) by those views passing archived:false; Filter.archived itself stays neutral (None = no restriction). |
| Link | A typed, ordered directed edge between two tasks. Types: child (structure) and blocks (dependency). The child graph is a single-parent tree (each task has exactly one structural home). The blocks graph is a DAG. |
| Tree view | A curated structure rooted at a task (or a virtual root), following child links, with manual order. A hand-built "list" is just a shallow tree. |
| Query view | A derived list: its members are the result of a filter + sort, not stored membership. This is what "list" usually means here (e.g. "what next", "due today"). A task appears in any number of query views for free. |
| Order | Two distinct notions. (1) Manual order = a child link's position among its siblings = priority in a tree view; reorderable by hand. (2) Query order = the sort of a query view (default: tree-priority — the path of positions; overridable, e.g. by due date). Query membership itself isn't hand-reordered; you change the underlying priorities. |
| Path / breadcrumb | The ancestor chain shown next to a task whenever it appears outside its home tree — i.e. in every query view and the blocks view. Essential, not cosmetic. (Your notes' "crumbean" = breadcrumb.) |
| Command | An intent to change state (CreateTask, Move, SetStatus, Claim, Assign, AddTag, Link, …). Run through guards first; applied only if allowed (see §5a). |
| Claim | A Claim command: an actor takes a todo task → wip, subject to the Assignment capability's guard. |
| Template | A reusable skeleton of child tasks ("steps") that can be instantiated under any task. |
[DECISION] "Are steps sub-tasks?" → Yes. Steps are modeled as child tasks, not a separate concept. A "template for steps" is therefore a template that instantiates a set of child tasks. This keeps one mechanism for everything and lets steps themselves have steps.
[DECISION] Structure is a single-parent tree. Each task has exactly one child parent (one structural home, one unambiguous breadcrumb). The only DAG is the blocks dependency overlay. "A task in multiple lists" is satisfied by query views, not by multiple structural parents. Consequences: subtree move = re-point one parent link; child cycle check is the simple "new parent isn't a descendant"; aggregation walks one unambiguous subtree.
Grouped and given IDs so the roadmap can reference them.
Capture & edit
FR-1Batch-create multiple tasks from the keyboard in one flow (e.g. one task per line).FR-2Each task: title, notes, tags. Edit any field.FR-3Templates: instantiate a predefined set of child tasks under a task.
Structure
FR-4Hierarchy of arbitrary depth viachildlinks.FR-5Each task has exactly onechildparent (single-parent tree). Multi-membership across "lists" comes from query views, not structure.FR-6Dependency links (blocks) form a DAG and drive non-default views (e.g. "blocked by").FR-7Manual ordering ofchildlinks = priority in a tree view; query views sort by a sort spec (default tree-priority).FR-8Move a task or a whole subtree to a new parent/position in one fast action.
Status & delegation
FR-9Status valuesdraft, todo, wip, paused, done(see §8);[DECISION]SetStatusaccepts any value, no transition guard — a person may drop straight back fromwiptodraft, for instance.draftis not claimable.FR-100–n assignees per task via the optionalAssignmentcapability; assignee may be a Person or an Agent.FR-11Claim: fromtodoonly; open to anyone if no assignees, else assignee-only (per theAssignmentcapability).[DECISION]assignees are hierarchical with/: an actorx/ysatisfies an assignment tox(or tox/yexactly), so a task may be assigned to a broad identity (e.g. a harness) and claimed/queried by a more specific one (e.g. the model it picked). Matching is one-directional (a specific actor covers a broader assignment, never the reverse) and applies equally toClaim,what-next-for, andclaimable-for.FR-12A parent task supplies context (its title/notes/path) to an assignee working a child.
Aggregation & views
FR-13Each capability defines its own subtree aggregation, rolled up current+descendants:Status→ progress %,TimeSpent→ sum,Estimate→ sum,Schedule→ earliest due. Adding a capability adds its roll-up, nothing else.FR-14Always render a task with its breadcrumb path in any non-default view.FR-15Fast navigation (jump, fuzzy find, expand/collapse, move focus) — file-manager-like.
Search & queries (this is what most "lists" are)
FR-23Free-text search over title/notes.FR-24Structured queries combining predicates:status,assignee,tag,within-subtree-of <task>,due(today / overdue / range),claimed?— with a sort spec.FR-25Saved & built-in parameterized queries, e.g. what next =status:todosorted by priority; what next for X under Y with tag Z =status:todo assignee:X within:Y tag:Z; due today =due:today.
Architecture-level
FR-26All mutations areCommands passed through capability/system guards (allow/deny with reason) before being applied (§5a).
Extended capabilities (added to support importing tasks from other tools, e.g. Super Productivity)
FR-27Recurrencecapability: completing a recurring task recomputes itsSchedulefrom the rule and resetsStatustotodo, instead of stayingdone— no per-occurrence task spawning.FR-28IssueRefcapability: a static external issue-tracker reference (provider/id/url) on a task, for context — no live sync.FR-29Attachmentscapability +BlobStoreport: link or file/image attachments, with actual bytes stored content-addressed when available.FR-30Archivedcapability: orthogonal toStatus; hidden from default views via a filter, not a separate structure (resolves §13 Q4).FR-31TimeLogcapability: per-day time-spent breakdown;TimeSpent(FR-13's aggregate) is recomputed as its sum whenever set.FR-32@nametitle syntax: on create or edit,@namein a task's title (outside inline/fenced code spans) is parsed out — stripped from the stored title — and addsnameas an assignee (additive, idempotent; seeFR-2/FR-10). The first of a planned family of special title syntax.FR-33#tagtitle syntax: on create or edit,#tagin a task's title (outside inline/fenced code spans) is parsed out — stripped from the stored title — and addstagto the task'sTags(additive, idempotent; seeFR-2/FR-24). Shares one scan withFR-32's@name(extract_title_syntaxintodoapp-core) so the title's code spans are only walked once; a future title syntax should extend that same scan rather than add a parallel parser.FR-34[...]due/recurrence title syntax: on create or edit, a[...]bracket in a task's title (outside inline/fenced code spans) is parsed out — stripped from the stored title only if its content parses — and sets the task'sScheduleorRecurrence. Dispatch order:YYYY-MM-DD[ HH:MM](absolute due),HH:MM(time-only, resolved against today), a weekday name (next occurrence), else a todoist/org-mode-style recurrence expression (daily,every N days,every mon,wed,fri,monthly, ...; mapped onto the existingRepeatCyclecases, not a full RRULE engine). SharesFR-32/FR-33's single scan (extract_title_syntax); "today" can't be read inside that pure core function (spec §5), so bracket parsing yields an unresolvedDueSpec, resolved againstClock::today()at thetodoapp-appcall site. The same grammar (DueSpec::parse/Recurrence::parseintodoapp-core) is reused wherever a due date or recurrence is set from free text outside the title: the TUI's manual due-date edit field and the CLI'stda set --due/--recurrenceflags — one parser, several entry points.FR-35Workspacecapability (see §3): binds a task subtree to a project folder/repo via{name, path?}on the subtree's root task. Tasks inherit it by nearest-ancestor lookup (workspace_of); cwd resolves to a workspace root by scanning root tasks for the deepest effective path containing it (workspace_root_for). [DECISION] The storedpathis only a default: per-machine overrides live in the local config's[workspaces]table, keyed byname— a shared database stays portable, folder mappings stay local. Surfaced in the CLI astda ws [init]and the--herequery flag.FR-36Agent work loop over the CLI (refinesFR-12/FR-18):tda show <id>(snapshot + parent/breadcrumb/children/blocked/workspace),tda context <id>(FR-12as prompt-ready Markdown: ancestor titles+notes, the task, children, workspace folder — self-contained so an agent can start a fresh session from it),tda note <id>(append-only timestamped progress notes;set --notesreplaces), andtda next --claimable --as <actor>(only tasks the actor may claim perFR-11: unassigned or listing them, not blocked). Actor ids for agents follow the<harness>/<model>convention (e.g.claude-code/fable-5) — plainIdstrings, no schema. The harness-side workflow lives inskills/tda/SKILL.md.
I/O
FR-16Export any list or branch to Markdown task list and to JSON.FR-17Import the same formats (round-trip withFR-16).
Interfaces (delivered across phases, all over the same core)
FR-18CLI usable by humans and scriptable by AI agents.FR-19TUI with full keyboard navigation.FR-20HTTP+JSON API.FR-21MCP server so agents can read/claim/update tasks as tools.FR-22GUI (later) sharing the TUI's keybindings and navigation model.
[DECISION] Hexagonal (ports & adapters), domain core has zero I/O dependencies. This is the part of your notes I'd lock in hardest — it's what makes the "core first, adapters later, fully tested" plan possible.
[DECISION] Composition-first domain (capabilities-as-components), ECS as inspiration, not a dependency. Composition is the modeling principle (see §3): a minimal Task identity with capability components attached à la carte, mirrored by the table-per-capability storage in §7. This is the good half of ECS — composition over inheritance — taken as a design pattern. We do not pull in an ECS engine (bevy_ecs or otherwise): no second in-memory World to sync against the durable store, no engine runtime in the core.
- The in-memory store (
todoapp-store-mem) is plain composed Rust — component maps keyed byTaskId(HashMap<TaskId, Status>, …), which is the ECS data shape without the framework. It sits behind the same repository ports as the Turso store, so it stays a swappable adapter. - If a real need for ECS-style systems/queries ever appears, it can be added later as just another store adapter behind the ports — the composition model already leaves the door open, with nothing to undo.
tda/
├─ crates/
│ ├─ todoapp-core/ # domain: entities, value objects, services, PORTS (traits). No I/O deps.
│ ├─ todoapp-app/ # use cases / application services orchestrating core + ports
│ ├─ todoapp-store-turso/ # adapter: persistence via the `turso` crate (impls the repo ports)
│ ├─ todoapp-store-mem/ # adapter: in-memory store, plain composed components (tests + fast dev)
│ ├─ todoapp-cli/ # adapter: clap-based CLI binary
│ ├─ todoapp-tui/ # adapter: ratatui TUI binary
│ ├─ todoapp-api/ # adapter: axum HTTP+JSON server
│ ├─ todoapp-mcp/ # adapter: MCP server for agents
│ └─ todoapp-ui-core/ # shared presentation logic: keymaps, navigation state (TUI+GUI share)
└─ Cargo.toml # [workspace]
todoapp-core and todoapp-app may be merged early if the boundary feels heavy; keep ports in todoapp-core regardless.
ComponentStore— capability-keyed access (ECS/column-store style):get<C>(id),set<C>(id, value),remove<C>(id)read/write/detach one capability at a time, keyed by taskId. Presence of a component is the capability. There is no whole-task load/save aggregate — a caller (or a guard) touches only the capabilities it needs, so heavy components likeNotesare read only when named. This is what makes the §7 table-split pay off. [DECISION] capability-keyed over an assembledTask/projection: a partial monolith is a mess to mutate and reconcile;store.get::<Status>(id)is the genuine column shape. Genericget<C>is not object-safe, so use cases hold a concrete store (Services<St>), not&dyn.TaskEntityStore— the minimaltaskentity:create/delete(delete cascades every component),touch(updated_at),meta(timestamps),all(ids).LinkRepository— create/remove/reorder links; query children, parents, dependents.CollectionRepository— saved trees & saved queries.QueryEngine— evaluate aQuery(filter + sort) over the store; returns task refs with their breadcrumb paths. Pure given a store snapshot, so it's directly unit-testable.Clock— injected time source (deterministic tests).IdGenerator— injected IDs (deterministic tests).BlobStore— content-addressed byte storage forAttachmentfile/image content (FR-29); separate fromComponentStoresince blobs aren't a per-task-capability row.
Use cases (in todoapp-app) are the only callers of ports. Adapters never call each other.
Async boundary. The turso crate is async (tokio), so the repository ports are async traits and use cases are async. [DECISION — supersedes the earlier "core stays sync & pure" call] Because capabilities are read capability-keyed on demand (ComponentStore, above), decide/apply (§5a) are themselves async and take the store: a guard gets only the components it inspects, and apply sets only what changed — no assembled snapshot to fold. QueryEngine-style evaluation still hoists its async component loads before the sync sort. The dependency rule is unaffected: ComponentStore is a port defined in todoapp-core; adapters implement it, so the core still imports no runtime/adapter. (Cost accepted: more loads and a non-pure decide; negligible for a local tool — ECS engines do far more per frame.) The todoapp-store-mem adapter implements these async traits trivially.
adapters → app → core. Nothing in core imports an adapter or a concrete framework. Enforce with a workspace check (e.g. a CI grep / cargo-deny-style rule that todoapp-core/Cargo.toml has no I/O crates).
All mutations flow through one small, pure shape — decide then apply — so that capabilities can veto commands and new behaviour is additive.
// Capability-keyed. Async over the ComponentStore port (a todoapp-core trait — no
// runtime/adapter in core). Lives in todoapp-core; orchestrated by todoapp-app.
async fn decide<St: ComponentStore>(store: &St, id: &Id, cmd: &Command, ctx: &DecideCtx)
-> Result<Vec<Event>, Denied>;
async fn apply<St: ComponentStore>(store: &St, id: &Id, event: &Event);decideruns the command through an ordered list of guards. A guard reads the capabilities it needs viastore.get::<C>(id)and returnsOption<Denied>. Guards come from:- capabilities —
Statusguards legal transitions;AssignmentguardsClaim(absent/empty ⇒ open; present ⇒ assignee-only); - systems — cross-cutting rules, e.g. the
blockssystem can denySetStatus(wip)while a blocker isn'tdone(a derivedblockedcheck). - First denial wins (or collect all — see §13). If none deny,
decidereturns the resultingEvents.
- capabilities —
applywrites each event back as components viastore.set/store.remove(a collection that becomes empty is removed — presence-as-capability, §7). The event seam is kept (a future audit/undo log can subscribe), it just isn't folded into an aggregate.
Right-sized on purpose (your "fast + simple to extend" constraint). This is the decider pattern, not full CQRS/event-sourcing:
- one Turso store, queried directly — no separate read/write models or projections;
- events are the internal result of a command, applied straight to state — no required event log (add one later for undo/audit without rearchitecting);
- a plain function call — no message bus or async command queue.
Cost of the whole mechanism: one Command enum, one Event enum, two async functions, and an ordered list of guards. Extension = add the capability's Component type (the generic store needs no change) + its Command/Event variant + a guard + an apply arm; nothing else changes.
| Concern | Choice | Notes |
|---|---|---|
| Language | Rust | Per your notes; good for CLI/TUI/perf. |
| Persistence | Turso (turso crate, embedded in-process, local file) |
The Rust rewrite of SQLite (MVCC, async I/O); SQLite-compatible SQL so the schema is unchanged. Async (needs tokio). Currently beta — acceptable for a personal dogfood tool; watch for rough edges. |
| Migrations | Embedded SQL migrations (simple runner, e.g. refinery or hand-rolled) |
Keep schema versioned from M2. |
| IDs | ULID (ulid crate) + git-style short display prefix |
128-bit, time-sortable, compact (26-char base32). Stable random id assigned at creation — not a content hash/CID (content mutates; a content hash would change on every edit). Random 128-bit ⇒ safe DB merge. [DECISION] ULID; UUIDv7 is the interop-safe fallback. |
| Serialization | serde + serde_json |
Export/import + API. |
| Errors | derive_more (Error/Display/From derives) in libs, anyhow in binaries |
Replaces thiserror; same ergonomics via derives, plus the other derive_more conveniences. |
| CLI | clap (derive) |
FR-18. |
| TUI | ratatui + crossterm |
FR-19. |
| HTTP API | axum |
FR-20. |
| MCP | rmcp (official Rust MCP SDK) |
FR-21; exposes tasks as agent tools. |
| Testing | std #[test], insta (snapshots), proptest (ordering/DAG invariants) |
|
| Async runtime | tokio |
Required by turso; also used by axum (API) and the MCP server. |
The blocks DAG, the single-parent child tree, and per-view ordering are the load-bearing decisions; everything else is conventional.
Composition mapping — one table per capability. The capabilities from §3 are stored the same way they compose in memory: a minimal task entity (id + timestamps) plus one component table per capability, keyed by task_id. The presence of a row is the capability — there is no "absent vs unknown" ambiguity, and add/remove = insert/delete. A new capability is a new table, touching nothing existing. List/tree views join only the components they render (task ⋈ c_title ⋈ c_status) and never load c_notes. The todoapp-store-mem component maps and these capability tables are two projections of the same component set (component map ⟷ component table) — the ECS-inspired shape, no engine required.
-- Actors: humans and agents
CREATE TABLE actor (
id TEXT PRIMARY KEY,
kind TEXT NOT NULL CHECK (kind IN ('person','agent')),
name TEXT NOT NULL
);
-- Minimal entity: identity only. Everything else is a capability component.
CREATE TABLE task (
id TEXT PRIMARY KEY, -- random immutable id; short unique prefix shown (see §6 / ID note)
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
-- Capability components: 1:1 with task, row exists iff the task HAS the capability.
CREATE TABLE c_title ( task_id TEXT PRIMARY KEY REFERENCES task(id) ON DELETE CASCADE, title TEXT NOT NULL );
CREATE TABLE c_status ( task_id TEXT PRIMARY KEY REFERENCES task(id) ON DELETE CASCADE,
status TEXT NOT NULL CHECK (status IN ('draft','todo','wip','paused','done')) );
CREATE TABLE c_notes ( task_id TEXT PRIMARY KEY REFERENCES task(id) ON DELETE CASCADE, notes TEXT NOT NULL ); -- Markdown, lazy-loaded
CREATE TABLE c_schedule ( task_id TEXT PRIMARY KEY REFERENCES task(id) ON DELETE CASCADE, due_date TEXT NOT NULL ); -- ISO-8601
CREATE TABLE c_estimate ( task_id TEXT PRIMARY KEY REFERENCES task(id) ON DELETE CASCADE, eta_minutes INTEGER NOT NULL );
CREATE TABLE c_timespent( task_id TEXT PRIMARY KEY REFERENCES task(id) ON DELETE CASCADE, minutes INTEGER NOT NULL );
-- Multi-valued capability components:
CREATE TABLE c_tag ( task_id TEXT NOT NULL REFERENCES task(id) ON DELETE CASCADE, tag TEXT NOT NULL,
PRIMARY KEY (task_id, tag) );
CREATE INDEX tag_by_name ON c_tag(tag);
CREATE TABLE c_assignment ( task_id TEXT NOT NULL REFERENCES task(id) ON DELETE CASCADE, actor_id TEXT NOT NULL,
claimed INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (task_id, actor_id) );
CREATE TABLE c_timelog ( task_id TEXT NOT NULL REFERENCES task(id) ON DELETE CASCADE, day TEXT NOT NULL,
minutes INTEGER NOT NULL, PRIMARY KEY (task_id, day) ); -- per-day breakdown; c_timespent stays the cached sum
CREATE TABLE c_attachment ( task_id TEXT NOT NULL REFERENCES task(id) ON DELETE CASCADE, attachment_id TEXT NOT NULL,
kind TEXT NOT NULL CHECK (kind IN ('link','file','image')), title TEXT NOT NULL,
url TEXT, blob_id TEXT REFERENCES blob(id), mime TEXT,
PRIMARY KEY (task_id, attachment_id) );
-- Nested/structured capability components: one JSON-serialized column each,
-- rather than one column per variant field.
CREATE TABLE c_recurrence ( task_id TEXT PRIMARY KEY REFERENCES task(id) ON DELETE CASCADE, data TEXT NOT NULL );
CREATE TABLE c_issueref ( task_id TEXT PRIMARY KEY REFERENCES task(id) ON DELETE CASCADE, data TEXT NOT NULL );
-- Presence-only capability component: no data column, the row IS the flag.
CREATE TABLE c_archived ( task_id TEXT PRIMARY KEY REFERENCES task(id) ON DELETE CASCADE );
-- Blob storage (`BlobStore` port): content-addressed, referenced by c_attachment.blob_id.
CREATE TABLE blob ( id TEXT PRIMARY KEY, content BLOB NOT NULL, created_at INTEGER NOT NULL );
-- Typed, ORDERED edges. `blocks` is many-to-many (DAG).
-- `child` is single-parent (tree): the `one_parent` index enforces ≤1 incoming `child` link per to_id.
-- `position` orders this link within its `from` node.
CREATE TABLE link (
from_id TEXT NOT NULL, -- parent task, virtual-root sentinel, or collection id
to_id TEXT NOT NULL, -- child / dependent task
kind TEXT NOT NULL CHECK (kind IN ('child','blocks')),
position REAL NOT NULL, -- fractional index → cheap reorders (see note)
PRIMARY KEY (from_id, to_id, kind)
);
CREATE INDEX link_from ON link(from_id, kind, position);
CREATE INDEX link_to ON link(to_id, kind);
CREATE UNIQUE INDEX one_parent ON link(to_id) WHERE kind = 'child'; -- single-parent invariant
CREATE TABLE collection ( -- saved trees & saved queries
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
kind TEXT NOT NULL CHECK (kind IN ('tree','query')),
spec TEXT -- for kind='query': JSON {filter, sort, params}; NULL for trees
);Notes:
- Fractional
position(a "fractional index": insert between two neighbors by averaging their positions) gives cheap manual reordering and subtree moves (FR-7,FR-8) without rewriting siblings. Re-balance lazily when gaps get too small. - Cycle prevention:
childis a tree — reject a re-parent if the new parent is a descendant of the moved task.blocksis a DAG — reject a newblocksedge that would close a cycle. Cover both with aproptest. - Aggregation (
FR-13) is computed by traversingchildlinks from a task; cache later if needed. - Curated list = shallow tree. A hand-built "list" is a
child-tree rooted at a virtual root node; no separate membership mechanism. - Identity & mergeability.
task.idis an immutable random ULID — assigned once, never derived from content, so edits never change it and links never dangle (the jj change-id model, vs a content hash that would churn). For the multi-DB merge case (e.g. CDviz across repos), prefix the id with a short per-database namespace (cdviz_01J9Z…): random ULIDs already won't collide, but the namespace carries provenance and keeps short-prefix lookups unambiguous across merged sources. A future optionalcontent_hash(blake3 of the task's canonical content) would let a merge detect divergent edits of the same id — that's a content hash used for conflict detection, kept separate from identity. Merge logic itself is post-v1, but none of these choices foreclose it.
A query is data, not code — stored in collection.spec (for saved ones) and evaluated by the QueryEngine port:
Built-ins ship as code-defined templates: what-next (status:todo sort priority), what-next-for (params assignee,within,tag), due-today (due:today sort due,priority). priority sort = tree-priority key (the path of positions), so a flat result still respects tree ordering.
Status is a required capability with five stored values. blocked is not a value — it's derived from unmet blocks deps. [DECISION] SetStatus is not guarded by a transition rule — any value may be set to any other directly (no stepping through intermediate states). The diagram below shows the common path and its usual verbs, but none of them are mechanically enforced.
promote start (Claim) complete
draft ──────────▶ todo ───────────────────▶ wip ───────────────────▶ done
◀──── demote ───┘ ◀──────── release ───┘ ◀──────── reopen ────┘
paused: a manual, off-path state a `wip` (or any) task can move
to and back from freely — e.g. blocked on something external.
derived: blocked = ∃ a `blocks` dependency whose blocker is not `done`.
Shown as a badge in any view; (optional guard) can deny `start` while blocked.
draft— capturable, refinable, commentable; not offered as work (excluded fromwhat-next).todo— ready/claimable; appears in "what next" queues. (synonym in prose: "ready".)wip— work in progress (claimed).paused— manually set aside; not offered as work. No dedicated verb/aggregation — just another value in free rotation.done— complete; rolls up into parent progress.
Claim rule (FR-11), driven by the Assignment capability — closes the earlier open question:
- allowed only from
todo; - if the task has no
Assignment/ zero assignees → anyone may claim, and claiming adds the claimer as assignee; - if it has assignees → only a listed assignee may claim, where a
/-delimited actorx/ycounts as the assigneex(hierarchical match,FR-11); - on success: set claimed, status →
wip.
The blocked badge is informational by default. Whether it should hard-deny start is a guard toggle — see §13.
A concrete starting surface so Claude Code has a target. Refine as you build.
tda add "Write spec" [--parent <id>] [--tag x --tag y] [--status draft]
tda add --batch # opens $EDITOR / reads stdin; one task per line, indentation = depth
tda ls [<id>] [--tree] [--query <name>] [--status todo]
tda mv <id> --to <parent-id> [--before <id> | --after <id>]
tda link <from> <to> --kind blocks
tda assign <id> <actor> tda claim <id> --as <actor>
tda set <id> [--title ..] [--notes ..] [--status draft|todo|wip|paused|done] [--due ..]
tda tag <id> <tag>...
tda show <id> # one task + parent/breadcrumb/children/blocked/workspace (FR-36)
tda context <id> # prompt-ready Markdown context: ancestors' notes etc. (FR-12/FR-36)
tda note <id> <text> [--as <actor>] # append-only timestamped progress note (FR-36)
# Search & queries (most "lists" live here)
tda find <text> # free-text (FR-23)
tda q [--status todo] [--as <actor>] [--under <task>|--here] [--tag <t>] [--due today|overdue] [--sort priority|due]
tda next [--as <actor>] [--under <task>|--here] [--tag <t>] [--claimable] # built-in: status:todo, by priority (FR-25; --claimable per FR-11/FR-36)
tda due today|overdue
tda q save <name> <...same flags...> # save a parameterized query
tda q run <name> [--as <actor>] [--under <task>] [--tag <t>] # bind params at run time
tda export <id|--query name> --format md|json
tda import <file> --format md|json [--parent root|default|<id>]
# --parent omitted or "default": wrap the import in a new root task named
# "<filename> <file mtime date>"
# --parent root: attach top-level items directly at the root (old behavior)
# --parent <id>: attach top-level items under that existing task
tda template save <id> <name> tda template apply <name> --to <id>
tda db init # create a local ./.tda/tda.db (git-style, idempotent)
tda db path # print the resolved database path
tda ws init [<path>] [--name <n>] [--root <id>] # bind a folder to a workspace root task (FR-35)
tda ws # print the workspace root resolved for cwd
[DECISION] Database resolution (CLI + TUI, shared): --db <path> flag >
nearest ancestor .tda/tda.db (walking up from cwd, like git — created only
by an explicit tda db init, so no surprise local dbs) > global default in
the OS data dir (~/.local/share/tda/tda.db). No env var override (YAGNI).
Enables per-project/isolated/test databases with zero per-call ceremony.
Design the CLI so every command emits machine-readable JSON with --json — this is the agent interface until the MCP server lands (FR-18/FR-21).
Milestones are ordered, each with deliverables and acceptance criteria Claude Code can check itself. Tackle them in order; each ends in a green test suite.
- Cargo workspace with the crates from §5 (empty
lib.rs/main.rsstubs). - CI:
cargo build,cargo test,cargo clippy -D warnings,cargo fmt --check. - Dependency-rule check:
todoapp-corehas no I/O deps. - Done when:
cargo testruns (even if empty) green in CI; workspace compiles.
- Entities/value objects:
Task(identity) + capability componentsTitle,Status,Notes,Schedule,Estimate,TimeSpent,Tags,Assignment;Actor,Link,Collection, fractionalPosition. Capabilities compose à la carte (see §3). - Ports: the traits in §5 (incl.
QueryEngine). todoapp-store-memin-memory adapter for tests.- Command machinery (§5a):
Command+Eventenums anddecide/apply, with per-capability guards (Statustransitions,Assignmentclaim rules,blocksstart-gate). Statically composed, no dynamic bus. - Use cases in
todoapp-app(each = build command →decide→apply→ persist via ports): create, batch-create, edit, move/reorder (subtree), link (with cycle rejection), tag, assign, claim, status transitions, aggregate subtree (per-capability roll-ups), evaluate query (filter + sort, with breadcrumb paths) + built-in queries (what-next,what-next-for,due-today), export-to-{md,json}, import. - Tests: unit per command incl. denial paths (claim a draft, claim by non-assignee, start while blocked);
proptestfor tree/blocks-DAG invariants and ordering; query tests per predicate + sort;instasnapshots for export. - Done when:
FR-1–FR-17,FR-23–FR-25provable against the in-memory store with noturso/UI/HTTP dependency anywhere incore/app.
todoapp-store-tursoimplementing all (async) repo ports via thetursocrate; versioned migrations matching §7.- A test suite that runs the same use-case tests from M1 against the Turso store (port conformance suite).
- Done when: every M1 use case passes against an on-disk Turso database; round-trip export→import is identity.
todoapp-cliexposing the §9 surface, backed by Turso, with--jsoneverywhere.tda importingests this very file (Markdown task list) into a tree;tda exportreproduces it.- Done when: you can run
tda import tda-spec.mdand then manage these milestones insidetdaitself. This is the "working ToDoApp that can store the roadmap" you asked for.
todoapp-ui-core: keymap + navigation state model (shared with future GUI).todoapp-tui(ratatui): tree/list views, expand/collapse, fuzzy find (FR-15), keyboard reorder & move (FR-8), breadcrumb rendering in non-default views (FR-14), batch capture (FR-1).- Done when: full create→organize→refine→claim loop is doable keyboard-only.
todoapp-api(axum HTTP+JSON) over the use cases.todoapp-mcp(rmcp) exposing read/claim/update/list-ready as agent tools (FR-21), so an assigned agent can pull context (FR-12) and workreadytasks.- Done when: an external agent can list ready tasks, read parent context, claim, and complete — end to end.
- Templates (
FR-3), richer dependency/blocked views (FR-6), aggregation caching, saved views. - GUI (
FR-22) reusingtodoapp-ui-corekeybindings. [OPEN: framework — see §13.]
- Core/app: pure unit tests; deterministic via injected
Clock/IdGenerator. Property tests for the two invariants that will bite hardest: DAG acyclicity and ordering correctness under inserts/moves. - Port conformance suite: one parametrized test set run against both
todoapp-store-memandtodoapp-store-turso. Adding a new store later means just passing this suite. - Snapshots (
insta): Markdown/JSON export — catches format regressions and proves round-trip. - Adapters: thin integration tests; keep logic out of adapters so there's little to test there.
v1 ships at M3 + M4: a keyboard-driven CLI and TUI over a Turso store, supporting arbitrary-depth hierarchy (single-parent tree) with a blocks dependency DAG, manual ordering, tags, query/search views ("what next", "due today"), assignees/claiming, the draft→done lifecycle, subtree aggregation, and Markdown/JSON round-trip — and able to host its own roadmap. M5/M6 are post-v1.
These are not resolved by the decisions above — they need your input (Claude Code can proceed on the suggested default and you correct later):
- Depth limit (
FR-4): your note said "no depth limit?". Suggest: unlimited, but a TUI render-depth cap for sanity. OK? - Denial aggregation in
decide(§5a): when several guards would deny a command, return the first denial (suggested — simplest, fastest) or collect all reasons (better UX for agents/forms)? Cheap to start with first-denial and switch later. - Aggregated status (
FR-13): how does a parent's status derive from{draft, todo, wip, paused, done}children — %doneby count (suggested), ETA-weighted, plus an optional manual parent override? Resolved: the orthogonaldonevs hidden: do completed tasks stay in the tree (greyed) or move to an archive view? Suggest stay, with a filter.Archivedcapability (§3/§7) — tasks stay in the store and tree, hidden from default views (what-next,due-today) via a filter, not moved to a separate structure.- API trust model (
FR-20/§2): local-only/no-auth for v1 (suggested), or a token from day one? - GUI framework (
FR-22): far off, but candidates are egui (Rust-native, pairs naturally with ratatui's immediate-mode feel) vs Tauri (web UI). No need to decide now. - Batch-create syntax (
FR-1): indentation = depth in the batch buffer (suggested), or flat-only with manual nesting after? - Multi-tag filter semantics (
FR-24):tag:[a,b]= match all (suggested) or any? And free-text (FR-23): substring (suggested) or FTS5 full-text later? @name/#tag/[...]title syntax (FR-32/FR-33/FR-34): should@mebe a reserved alias (vs. a literal actor id, same as any other name)? Is the trigger character set ([A-Za-z0-9_-], shared by the first two) final? Is the[...]recurrence grammar (daily/every N days/every <weekdays>/monthly/every N months) sufficient, or should it grow toward a fuller RRULE-like syntax? All three now share one scan (extract_title_syntaxintodoapp-core) rather than parsing the title multiple times — a future title syntax should extend that same function instead of adding a parallel scanner, so order/precedence stays implicit in a single left-to-right pass.
Read
tda-spec.md. Execute M0 then M1 only. Set up the Cargo workspace per §5, then implement the domain core and use cases per §3–§9 against an in-memory store, with the full test suite from §11. Do not add Turso, CLI, TUI, or HTTP yet. Treat the §5 dependency rule as inviolable: nothing intodoapp-core/todoapp-appmay depend on an adapter or I/O crate. Stop after M1 with a greencargo testand a short summary of the use cases implemented.
{ "filter": { "text": "string?", // free-text over title/notes "status": ["todo"], // any-of: draft|todo|wip|paused|done "assignee": "actor_id?", "tag": ["tag"], // all-of (or any-of — see §13) "within": "task_id?", // tasks in the subtree of this task "due": "today | overdue | {before|on|after: <date>}?", "claimed": "true | false?" }, "sort": [{ "key": "priority|due|created|updated", "dir": "asc|desc" }], "params": ["assignee", "within", "tag"] // unbound holes for parameterized/built-in queries }