Topics and relations

What is a topic?

A topic is the atomic unit of context in Driftless. It connects a slice of your system to the team’s shared knowledge about it. The slice can be TypeScript, Python, Rust, Go, docs, config, infrastructure, or a workflow that spans repos. A topic has:

Field	Description
slug	Unique kebab-case id within the workspace (e.g., `auth-flow`, `billing-webhook`)
title	Short human display name: a noun like a diagram node (`Auth`, `Billing`). Keep it to one or two words; the explanation goes in `what`/`content`, never the title
what	Short summary of what this code does
how	Short note (1-3 sentences) on the mechanism or approach. Long-form explanation belongs in `content`, not here
decisions	Why choices were made (architecture decisions)
gotchas	Traps, edge cases, things that will break
invariants	Rules that must always hold true
required_checks	Checks to run before changing this code
ownership	Team or individual responsible
content	Full free-form body (Markdown). Can include diagrams, code snippets, references
anchors	Patterns, files, and repos that link this topic to code
tags	Workspace categories for discovery and filtering (e.g., `auth`, `billing`): filter with `context list/search --tag <name>`, the MCP `tags` param, or the dashboard chips. Pre-create and curate them in the registry (`driftless tags`)
relations	Typed links to other topics
classification	Status (`reviewed`, `draft`)

Topics are content-first: the markdown content body IS the topic. The structured fields (gotcha / decision / invariant / check) are optional highlights layered on top. Add one only when you want that specific thing surfaced to a future agent’s brief. Use tags to label and group topics.

Create your first topic

Start with the smallest useful topic: a durable note that explains one area well enough for a future human or agent to work there.

# The first topic should be something REAL: the gotcha that bit you, the
# invariant nothing may break, anchored to the module it governs:
driftless context add billing-webhooks --title "Webhooks" \
  --what "Stripe webhook ingestion and its idempotency rules." \
  --gotcha "Stripe delivers at-least-once: handlers must short-circuit on a seen event.id" \
  --pattern "src/billing/webhooks/**"

Then enrich it as reality becomes clear:

driftless context update billing-webhooks \
  --gotcha "..." \
  --decision "..." \
  --check "..."

Anchoring topics to code

Topics are connected to code through glob patterns and file paths. This is language-agnostic: Driftless matches paths, not ASTs. When anchored code changes, the topic drifts.

# Anchor by glob pattern
driftless context add api-guards --pattern "src/auth/**"

# Multiple patterns for cross-cutting topics
driftless context update api-guards --add-pattern "src/common/guards/**"

# Anchor by exact file path
driftless context add auth-flow --where src/auth/guard.ts

# Anchor a document
driftless context add architecture-decisions --file docs/decisions/auth.md

The CLI validates every pattern against your local checkout at write time:

✓ pattern "src/auth/**" matches 12 files: healthy anchor
⚠ over-broad anchor: pattern matches over 100 files; consider splitting
✗ pattern "src/nonexistent/**" matches 0 files: blocked; fix the glob

Discipline: 5-40 matched files per topic is healthy. Fewer than 5 means you’re fragmenting. More than 100 is a catch-all trap that nobody will maintain. If a topic covers too much, split it; if it covers too little, merge it. Remove anchors when they no longer make sense:

driftless context update auth-flow --remove-pattern "src/old-auth/**"

Topic classification

A topic is content-first: the markdown content body IS the topic. Use tags to label and group topics. The only trust axis is status.

Status: governance lifecycle

A note becomes Knowledge once it’s merged in: draft → proposed → reviewed → archived. reviewed is Knowledge; the read response carries governance.authoritative. Agents propose; merging is an owner/admin act (an agent runs it only when explicitly asked). See Governance.

Status	Meaning
`draft`	Captured, not yet merged in: a hint (a Note), not truth
`proposed`	Up for review
`reviewed`	Knowledge: an owner/admin merged it in (or an agent did on their request); the agent treats it as truth
`archived`	Retired
`orphaned`	Code-driven (repo deleted), orthogonal to governance

Visibility

A topic lives in the workspace and is visible to all its members. The exception is a private Note (a draft with is_private set), visible only to its creator until put up for review or un-marked. Need isolation between groups? Use a separate workspace.

Typed relations

Topics connect to each other through typed relations, building a semantic graph:

Relation	Meaning
`depends_on`	Topic A depends on B
`relates_to`	General association
`supersedes`	Topic B replaces A
`blocks`	A cannot proceed until B is done
`implements`	A is the implementation of the pattern described in B
`documents`	A documents or explains B
`risk_for`	A introduces risk for B

driftless context update auth-guard \
  --rel depends_on:jwt-service \
  --rel relates_to:role-decorator

Wiki-links

Use [[slug]] syntax inside any free-text field (what, how, decisions, gotchas, invariants, content). The API auto-parses these into forward and backward references.

driftless context update billing-webhook \
  --gotcha "Same idempotency race as [[stripe-webhook-ingest]]; deduplicate by event ID"

Both billing-webhook and stripe-webhook-ingest will show each other in their references when fetched.

Cross-repo context

A topic can span multiple repositories. When you run driftless context update <slug> from any repo, that repo is added to the topic’s where_repos list. Topics accumulate repos organically without manual wiring. Use one cross-repo topic when the same concept truly spans repos, for example billing-contracts across an API repo, worker repo, and frontend repo. Use separate topics plus relations when each repo has its own implementation details, for example billing-api depends_on:billing-worker. To explicitly link the current repo to a topic:

driftless context link auth-flow

The topic graph

The topic graph is explorable from CLI and dashboard:

driftless context graph auth-flow    # BFS graph from a topic, terminal output

The dashboard renders the full interactive graph. Nodes are topics, edges are typed relations. Click any node to see its full context and anchors.

Get started

Connect

Concepts

Work & collaborate

Guides

Agents

MCP reference

CLI reference

API reference

Platform

Topics and relations

What is a topic?

Create your first topic

Anchoring topics to code

Topic classification

Status: governance lifecycle

Visibility

Typed relations

Wiki-links

Cross-repo context

The topic graph

​What is a topic?

​Create your first topic

​Anchoring topics to code

​Topic classification

​Status: governance lifecycle

​Visibility

​Typed relations

​Wiki-links

​Cross-repo context

​The topic graph

What is a topic?

Create your first topic

Anchoring topics to code

Topic classification

Status: governance lifecycle

Visibility

Typed relations

Wiki-links

Cross-repo context

The topic graph