Add canonical engineering glossary (GLOSSARY.md)#284
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive GLOSSARY.md to establish canonical terminology for the Scion platform and adds a reference to it in agents.md. The review feedback highlights a typo in agents.md and notes that several existing shorthand definitions in that file contradict the new glossary. Additionally, the reviewer suggests refining the workstation mode description in the glossary's comparison table to improve clarity and consistency.
|
|
||
| ## Short hand gossary and project development terminology | ||
|
|
||
| > **Canonical engineering glossary:** See [`GLOSSARY.md`](./GLOSSARY.md) at the repo root for the canonical, opinionated terminology used throughout the codebase — the preferred term for each concept and the synonyms to avoid. Prefer these terms in new code, comments, and docs. |
There was a problem hiding this comment.
While adding a reference to the new canonical glossary is excellent, the section header on line 85 contains a typo (gossary instead of glossary). Additionally, the shorthand definitions immediately below (lines 89–94) contain several outdated terms (such as hub-native, hub-project, linked-project, agent-home, and hub-broker) that directly contradict the newly established naming rules in GLOSSARY.md. Please correct the typo in the header and clean up or remove the redundant/outdated shorthand definitions below to ensure GLOSSARY.md remains the single source of truth.
| | Mode | Server | Tenancy | State & isolation | Canonical use | | ||
| |------|--------|---------|-------------------|----------------| | ||
| | **Local mode** | None | Single user | Local machine; isolation via git worktrees | Agents launched directly via the `scion` CLI, no server | | ||
| | **Workstation mode** | Combo server (Hub + Runtime Broker + Web) on loopback | Single-tenant | That machine | The hosted experience locally, on your own machine | |
There was a problem hiding this comment.
In the comparison table, the State & isolation description for Workstation mode is currently written as "That machine". This is somewhat informal and less descriptive compared to the other entries (e.g., "Local machine; isolation via git worktrees" or "Hub-coordinated across brokers"). Consider updating it to "Local machine; single-tenant state" for better clarity and consistency.
| | **Workstation mode** | Combo server (Hub + Runtime Broker + Web) on loopback | Single-tenant | That machine | The hosted experience locally, on your own machine | | |
| | **Workstation mode** | Combo server (Hub + Runtime Broker + Web) on loopback | Single-tenant | Local machine; single-tenant state | The hosted experience locally, on your own machine | |
…up tracker Add a root-level GLOSSARY.md capturing canonical Scion terminology in the ubiquitous-language format (preferred term + synonyms to avoid), grouped by domain cluster, plus an Exceptions & Future Cleanup section tracking known naming-convergence work. Link it from agents.md as the canonical engineering glossary.
…inements Refine entries from review: redefine Message Broker as the pluggable messaging-integration system (add Broker plugin, Built-in broker); add Event Bus for the NATS real-time/event capability; collapse hub-native/Hub Workspace into Hub-managed project/workspace; tighten Template (harness-agnostic, optional default harness-config), Skill (template-only, Agent Skills link), Profile (named runtime-broker settings bundle), Harness/Harness-config; reframe Hub as the control plane in both modes; add Group and Message Group. Expand Exceptions & Future Cleanup to nine tracked items.
…terms - Retitle to "Scion Glossary"; drop the "Language" wrapper and promote the thematic categories to top-level sections - Add an Operations section (Attach, Dispatch) and move Profile next to Runtime Broker - Add a Local/Workstation/Hosted comparison table and "See also" cross-refs across the main confusable term clusters - Reframe the intro around the three-way broker collision (incl. Event Bus) and defer to the disambiguation rule; sentence-case "Shared directory" - Add canonical entries for Secret, Notification, and Schedule - Add a "Potential Future Additions" section cataloguing candidate terms
The cleanup items are now tracked by dedicated agents that open GitHub issues and implementation PRs, so the staged tracker no longer lives in the glossary. Reword the two intro/disambiguation references that pointed at the removed section to point at GitHub issues instead.
…tion state - agents.md: fix 'gossary' typo in section header; remove shorthand definitions (hub-native, hub-project, linked-project, agent-home, hub-broker) that contradicted the canonical GLOSSARY.md - GLOSSARY.md: clarify Workstation mode State & isolation column
1 participant
Restaged for upstream submission. Original fork PR #102 was accidentally merged into fork main (now reverted).
Summary
Adds
GLOSSARY.md— a canonical engineering glossary that fixes the preferred term for each domain concept so that code, docs, UI, and prompts share one vocabulary.Key naming rules established:
Covers all major subsystems: Agents, Hub & Hosted, Runtime Broker, Message Broker, Event Bus, Templates, Harness, Project, Secrets, Telemetry, CLI, and Notification concepts.
Closes #[issue not yet filed upstream]