Skip to main content
A comment is a thin annotation that points AT something (a topic, a record, or a project card) and optionally at one of its fields. It is the lightweight way for humans and agents to coordinate over content without editing it. A comment is deliberately not a topic. It has no version, no drift, and no governance of its own; its text never enters the topic body. Topics are the durable why; comments are transient coordination that resolves into an edit.

​
What a comment is

  • Points at a spine object or a card. target_kind is one of topic, record, or card; target_id (or, for a topic, its slug) says which one. An optional field_key scopes the comment to a single field (e.g. decisions).
  • Authored by a human or an agent. Agent-authored comments are what set this apart: an agent can flag a contradiction on a field and a human sees it on the next refresh, or the other way around. That is what makes the workspace genuinely collaborative between humans and agents.
  • Has a small state machine. open → resolved → wont_fix. When an edit addresses a comment, its author (human or agent) marks it resolved. There is no auto-regenerate. Comments resolve, they don’t rewrite the document.
  • Async, not realtime. Comments appear on pull/refresh. No live cursors.

​
The killer placement: the Note → Knowledge gate

Promoting a Note into Knowledge is normally a coarse, binary act: approve or reject. Comments turn that gate into fine-grained, field-level feedback at review time. A reviewer (or an agent) can pin a precise objection to the decisions field of a note, the author addresses exactly that, and the merge happens faster and comes out better. Listing a topic’s open comments by slug is the reviewer’s view of the gate.

​
Using comments

From the CLI (the surface also exists in MCP as driftless_context_comment): 
# Leave feedback on a topic, scoped to a field
driftless context comment add billing-flow --body "This decision contradicts the refund invariant" --field decisions

# On a card or a record (by uuid)
driftless context comment add --card <card-uuid>   --body "Blocked on the webhook fix"
driftless context comment add --record <record-uuid> --body "Duplicate of the Globex lead"

# The reviewer's view, then resolve
driftless context comment list billing-flow --status open
driftless context comment resolve <comment-id>          # or --wont-fix, or `reopen <id>`
Comments are workspace-scoped and respect the same tenant boundary as every other object: a comment can only point at a target that lives in the same workspace.