Skip to main content

​
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:
FieldDescription
slugUnique kebab-case id within the workspace (e.g., auth-flow, billing-webhook)
titleShort 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
whatShort summary of what this code does
howShort note (1-3 sentences) on the mechanism or approach. Long-form explanation belongs in content, not here
decisionsWhy choices were made (architecture decisions)
gotchasTraps, edge cases, things that will break
invariantsRules that must always hold true
required_checksChecks to run before changing this code
ownershipTeam or individual responsible
contentFull free-form body (Markdown). Can include diagrams, code snippets, references
anchorsPatterns, files, and repos that link this topic to code
tagsWorkspace 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)
relationsTyped links to other topics
classificationStatus (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 the machine (the PR bot, 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.
StatusMeaning
draftCaptured, not yet merged in: a hint (a Note), not truth
proposedUp for review
reviewedKnowledge: an owner/admin merged it in (or an agent did on their request); the agent treats it as truth
archivedRetired
orphanedCode-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:
RelationMeaning
depends_onTopic A depends on B
relates_toGeneral association
supersedesTopic B replaces A
blocksA cannot proceed until B is done
implementsA is the implementation of the pattern described in B
documentsA documents or explains B
risk_forA introduces risk for B
driftless context update auth-guard \
  --rel depends_on:jwt-service \
  --rel relates_to:role-decorator
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.