Skip to content

Contextive Glossary Integration

Who is this for (1)

Spec Kitty generates Contextive-compatible YAML glossary files from the canonical glossary markdown so that IDE users get in-editor term hover panels without any manual duplication.

How it works

Contextive glossary generationThe generator reads the canonical term pages in docs/context and the traceability map, then writes one context YAML per referenced context and one scope YAML per mapped package.

docs/context/{slug}.md
canonical term definitions (edit here)

.kittify/traceability/contextive-map.yaml
scope to context mapping

scripts/generate_contextive_glossaries.py

src/specify_cli/.contextive/{slug}.yml
one per referenced context

{scope path}/.contextive.yml
imports the scope's contexts

The generator reads the canonical term pages in docs/context and the traceability map, then writes one context YAML per referenced context and one scope YAML per mapped package.

In words: the generator reads every context page the map references and the map itself, then writes one context YAML per referenced context and one scope YAML per mapped package.

  • Context YAMLs (src/specify_cli/.contextive/<slug>.yml) contain the extracted terms for one glossary context domain.
  • Scope YAMLs (<scope path>/.contextive.yml, for example src/glossary/.contextive.yml) use Contextive imports: to pull in only the contexts relevant to that package. This keeps files small and avoids copying definitions.

The mapping from source package → relevant contexts is in .kittify/traceability/contextive-map.yaml.

Running the generator

Terminal window
# Write / update all generated files
python scripts/generate_contextive_glossaries.py generate
# Check that generated files are up-to-date (exits 1 if stale)
python scripts/generate_contextive_glossaries.py check

Where the mapping lives

.kittify/traceability/contextive-map.yaml — single source of truth for what gets generated where.

context_base_dir: "src/specify_cli/.contextive"
scopes:
- path: "src/glossary"
description: "Core glossary subsystem"
contexts:
- lexical
- system-events

Adding a new scope mapping

  1. Open .kittify/traceability/contextive-map.yaml.
  2. Add a new entry under scopes:
    - path: "src/specify_cli/my_new_package" # illustrative path
    description: "What this package does"
    contexts:
    - orchestration # choose from docs/context/ filenames (without .md)
  3. Run the generator:
    Terminal window
    python scripts/generate_contextive_glossaries.py generate
  4. Commit the updated map together with every file the generator wrote: the new scope .contextive.yml and any new context YAML under src/specify_cli/.contextive/.

Available context slugs

A context slug is a filename (without .md) under docs/context/. The generator checks only that the file exists; it extracts terms from a page that has a ## Context: heading followed by ### term entries with a definition table. These pages have that shape today:

SlugDomainMapped to a scope today
charterCharter domain model and artifact taxonomyno
configuration-project-structureProject layout and configuration artifactsno
dossierArtifact inventory and drift detectionyes
executionCLI invocation and semantic safety gatesyes
governanceCharter, ADR, and policy precedenceyes
identityActors, roles, and Human-in-Chargeno
identity-fieldsRepository, collaboration, and build identity fieldsno
lexicalGlossary internal data modelyes
orchestrationMission, work package, and Mission lifecycleyes
planning-and-trackingIssue tracker organization and dispatchno
practices-principlesWorking agreementsno
product-linesSpec Kitty product linesno
system-eventsEvent envelope and glossary evolutionyes
technology-foundationsGeneral tech terms (API, CLI, YAML, Git)yes
testing-taxonomyTest categories and pytest markersno
topologyMission topology and where work runsno

Only a mapped slug gets a context YAML. The header comment in contextive-map.yaml lists 11 slugs; the map’s scopes reference seven.

Keeping the generated files current

No CI workflow runs check against the repository today. The tests in tests/cross_cutting/encoding/test_contextive_traceability.py exercise the generator on fixtures and parse the real context pages; they do not compare the committed files with a fresh generation. Run check yourself after you edit a page under docs/context/, and commit the regenerated file with the page. check exits 1 and names each stale or missing file.

Do not edit generated files

All files under src/specify_cli/.contextive/ and any <package>/.contextive.yml file whose first line reads # GENERATED FILE are machine-generated. Edit the canonical sources instead:

  • Term definitions → docs/context/<slug>.md
  • Scope mapping → .kittify/traceability/contextive-map.yaml