Skip to main content

ADR-009: Tasks, Items, and KB Documents are three distinct first-class concepts

Status​

Proposed — 2026-05-25. Definitional.

Date​

2026-05-25

Context​

The platform already has two markdown-or-structured content types attached to a Work:

  • Items — catalog entries (directory rows, blog posts, …). The thing a Work outputs. Stored under <dataRepo>/items/<slug>.json (or .md for content-heavy items). Generated by the standard pipeline.
  • KB Documents — knowledge-base entries that augment a Work's prompts. Stored in work_knowledge_documents (DB) and edited via the Tiptap-based KbEditor.

The new Task-tracking feature (features/task-tracking/spec.md) introduces a third content type with rich metadata: status, priority, assignees, chat. There's a real risk users (and engineers) will confuse the three, especially because all three render in some kind of list/detail UI.

This ADR pins the distinction so we don't later end up arguing whether to merge Tasks into Items or KB into Tasks.

Decision​

Tasks, Items, and KB Documents are three independent, non-overlapping first-class concepts. They will not be merged, unified, or mutually substituted.

The distinction​

AspectItemKB DocumentTask
What it isA row in the Work's output catalog.A reference document that augments the Work's prompts.A unit of work to be done.
Who caresEnd readers of the deployed site / directory.The AI generators when writing/refining the Work.The user + Agents collaborating on the Work.
MutabilityMutated by the generator; manual edits supported.User-authored; AI may suggest but doesn't auto-edit.Highly mutable — status, assignees, chat update constantly.
LifecycleCyclical — items refreshed on every generator run.Long-lived; revised occasionally.Short-lived per task; deleted/done state common.
Persistence<dataRepo>/items/* + DB cache.DB (mutable) with optional Git mirror.DB (high write rate; Git would thrash).
Identityslug, scoped to the Work.id, hierarchical (folder tree).slug = T-N (per-user counter), polymorphic scope (Work/Mission/Idea/Tenant).
RelationsTagged with categories; references KB.References items (via wikilink); referenced by tasks.References KB (mentions), items (mentions), other tasks (sub/blocker/related), agents (assignees).
AI surfaceAI generates them; AI rarely edits one task at a time.AI reads them as context; AI rarely writes them.AI assignees can work on them, comment, transition status.
UIItems tab on Work detail; the deployed site itself.KB tab on Work detail; Tiptap editor.Tasks tab on Work/Mission/Idea detail; /tasks page; Kanban view.

What to do when a contributor is tempted to blur the lines​

  • "Should this be an Item or a Task?" If the thing is consumer-facing content (a blog post, a directory entry, a comparison page), it's an Item. If it's "build this", "review this", "fix this," it's a Task.
  • "Should this be a KB Document or a Task?" If the thing is reference material the model reads (a doc, a runbook, a glossary), it's KB. If it has an assignee and a status, it's a Task.
  • "Should the Task description live in KB?" No. The description lives on the Task. KB documents may be mentioned in a Task description via wikilinks ([[doc-slug]]), but the description is the Task's own field.

What about Skills?​

Skills sit alongside KB as the model's "knowledge how to do things," whereas KB is "knowledge of things." They're distinct again: Skills are scoped, versioned, AI-invokable units; KB is a free-form reference library.

What about Ideas? [F3 operator clarification — round 8]​

Tasks and Ideas are also distinct, despite both being unit-of-work-shaped:

  • Idea = a proposal to build something new (a Work). Auto-generated by the Work Agent / Mission tick / Generators, easily dropped, never about bugs. Closest PM term: "Epic" — but even that doesn't quite fit. From one Idea, 0..N Works can be spawned.
  • Task = a specific unit of work to be done. Authored intentionally. Mutable. Lifecycle covers bugs / refactors / audits / implementation. Lives at Work / Mission / Idea / tenant scope.

An Idea may have its own Tasks (for validity checks, market research, prototyping). These stay on the Idea — they do not auto-forward to Works derived from the Idea (see features/task-tracking/spec.md §5.7).

Full distinction table: features/task-tracking/spec.md §1.1.

Consequences​

Positive​

  • Clean mental model for users. Items = output, KB = reference, Tasks = work-in-flight.
  • Clean code boundaries. Three modules, three controllers, three repositories — no shared base class with awkward conditional behavior.
  • Independent evolution. Tasks can add status, priority, recurrence; Items can add SEO fields; KB can add chunking/embeddings — without colliding.
  • Predictable AI behavior. Agents know which surface to act on for each verb. No "should I edit the KB or create a Task?" branching at every step.

Negative​

  • Some duplication of UI conventions. All three render markdown bodies via Tiptap; all three accept attachments. Mitigated by: shared editor component, not shared entity.
  • More tabs on Work detail page. Items, KB, Tasks are three separate tabs (plus Plugins, Agents, Skills, Deploy, Settings, Generator, Activity, Overview). Mitigated by: tab strip is already visually compact in WorkTabs.tsx.

Alternatives Considered​

1. Merge Tasks into Items as "internal items"​

Rejected. Items are public-facing; Tasks are workflow. Putting Tasks in the items table would force Items to grow assignee/status/chat columns nobody else uses, and would leak workflow data into the public site.

2. Merge Tasks into KB as "actionable KB documents"​

Rejected. KB is reference; Tasks are mutable workflow. Their write patterns are completely different (KB: occasional revision; Tasks: constant status churn).

3. A single content table with discriminator column​

Rejected. Tried-and-failed pattern. Discriminator unions get half-typed columns nobody fully uses, indexes that suit none of the access patterns, and queries that branch by type on every read.