Vocabulary Redesign

Workshop for redesigning the KB's vocabulary: the terms that appear in always-loaded context, definition notes, collection conventions, link labels, type names, and review/survey prose.

Question

What vocabulary should commonplace ask every agent and maintainer to learn, and what should stay local to a note, collection, or workshop?

The current vocabulary is useful but has grown through local problem solving. Some terms are central and stable (context engineering, distillation, constraining, codification, register, workshop). Others may be overloaded, too abstract for always-loaded context, or split across link labels, type names, artifact roles, and review terminology. The redesign should keep the vocabulary small enough to teach, precise enough to guide writing and review, and operational enough to change agent behavior.

Scope

In scope:

  • Terms in the AGENTS.md Vocabulary section.
  • Definition notes under kb/notes/definitions/.
  • Link labels and relationship vocabulary in kb/reference/link-vocabulary.md.
  • Artifact-role words used across notes, references, instructions, reviews, and source ingests.
  • Naming conventions for collections, types, traits, statuses, registers, and workshop/library boundaries.

Out of scope unless needed for a vocabulary decision:

  • Rewriting all notes to match the new vocabulary.
  • Changing validators, schemas, or generated indexes.
  • Adding a new type system or ontology.

Working Principles

  • Prefer fewer terms with sharper boundaries over a larger taxonomy.
  • A term earns always-loaded status only when misuse causes repeated bad decisions.
  • Definition notes should explain operational consequences, not only prose meanings.
  • Vocabulary changes should include migration notes: old term, new term, when to use each, and what existing artifacts need updates.
  • Keep external-theory borrowings subordinate to local workflow needs.

Initial Questions

  • Which current terms are foundational enough to remain in AGENTS.md?
  • Which terms should move from always-loaded vocabulary into on-demand definition notes?
  • Are distillation, constraining, and codification still the right operator set, or do we need a clearer hierarchy?
  • Does register still belong as a primary term, or should collection-level roles be named differently?
  • Are link labels organized around writer needs, reader needs, register boundaries, or artifact roles?
  • Where do memory, context, knowledge, artifact, system-definition, instruction, skill, and source currently blur?

Outputs

Candidate durable outputs:

  • Revised AGENTS.md Vocabulary section.
  • Updated definition notes or new definition notes.
  • A vocabulary migration note under kb/reference/ or kb/notes/.
  • Revisions to kb/reference/link-vocabulary.md.
  • Review gates or validation warnings if a term boundary can be checked.

Working Files

Closure

Close this workshop when there is a concrete vocabulary proposal with:

  • keep / revise / demote / remove decisions for the always-loaded terms;
  • a migration plan for affected notes and reference docs;
  • explicit open questions left for later rather than hidden in the vocabulary.

Grounding