Repository navigation
docs: Factor contributor and agent terminology out of docs and skills into a canonical glossary #5271
Description
User Story
When coordinating work on OpenShell through its contributor instructions and skills, I need terms such as “accepted work” to have one authoritative definition in one and only one specific location for documentation and skills to refer to so every agent uses them consistently and follows the intended workflow.
Problem Statement
Let's DRY up our docs and skills by making one source of truth for core terminology that we consistently refer to from docs and skills rather than defining and redefining in multiple places.
OpenShell's workflow vocabulary is explained across AGENTS.md, CONTRIBUTING.md, contributor skills, and GitHub label descriptions. There is no shared terminology glossary for instructions to reference. Repeating or paraphrasing definitions across these surfaces makes it easy for meanings to drift or for agents to infer different permissions from the same term.
Further, many terms are explained in multiple locations which creates the opportunity for definitions to drift over time as agents make corrections to some but not all of the places where a term is defined.
“Accepted work” is a motivating example: agents need to distinguish a maintainer's decision to pursue an issue from technical validation, implementation readiness, and authorization to perform a particular phase in response to a direct request. We talk around this in our triage skills and PR review readiness workflow, and the first agentic attempt to explicitly define it (#5260) started by writing it in three skills and two doc files.
Impact / Why This Matters
Contributors and agents currently have to reconstruct meanings from multiple documents and live repository state. Ambiguity can cause unnecessary clarification, premature implementation, incorrect status changes, or avoidable PR gating failures. Maintaining equivalent prose in several places also increases the cost of changing a workflow rule.
Proposed Design
Consider adopting Matt Pocock's domain-modeling skill which is specifically intended for this and easily separable from his other skills. Otherwise, the agent suggests this course of action:
Provide a discoverable, canonical glossary for OpenShell contributor and agent workflow terminology. Define each term once, with a stable reference that instructions and skills can link to instead of restating its definition. Keep procedural steps where they belong, and distinguish those steps from definitions.
Start with the vocabulary that affects authority and issue disposition: accepted work, triage, technical validation, implementation readiness, phase authorization, and roadmap placement. Confirm the exact initial terms and definitions against current maintainer policy. Entries should explain who can make the relevant decision, what evidence establishes it, and what it permits; include short examples where similar terms are easily confused.
Make consulting and using the glossary part of agent instructions. Update existing contributor instructions and relevant skills to reference the canonical entries and remove duplicated definitions. Future terminology or workflow changes should update the definition and its references together.
The glossary must coexist with the requirement to discover current GitHub labels and descriptions: explain conceptual meaning and link to the authoritative live state where applicable, without freezing a second label inventory or silently changing existing policy. Public installable skills must retain access to any definitions they need without requiring a source checkout.
Suggested UX
A contributor or agent encountering “accepted work” follows its glossary link to one definition and a brief example distinguishing it from “technically validated.” An instruction that requires acceptance references that entry and states the action-specific requirement. A direct request to investigate an issue is understood as authorization for that phase; issue disposition is evaluated separately under the existing workflow.
Acceptance Criteria
- A canonical glossary defines the agreed initial workflow terms, including “accepted work,” with stable links to individual entries.
- Definitions distinguish acceptance, technical validation, implementation readiness, phase authorization, and roadmap placement without changing existing maintainer policy.
-
AGENTS.md,CONTRIBUTING.md, and relevant contributor skills direct agents to the glossary and use its terminology consistently. - Duplicated definitions are replaced with references; procedural requirements remain clear at their point of use.
- Representative examples cover technically validated work without acceptance, a direct request authorizing investigation only, and accepted work subject to applicable implementation or PR requirements. The instructions resolve each case consistently.
- A documented consistency check or review step detects terminology drift, duplicate definitions, and broken glossary references when workflow instructions change.
- Live label discovery remains authoritative for current repository state, and any affected public skills remain usable outside a checkout.
Alternatives Considered
- Continue explaining terms independently in each instruction or skill. This preserves local context but retains the duplication and drift problem.
- Use only GitHub label descriptions. These describe live state, but do not cover all workflow concepts or explain how authorization and disposition relate.
- Put all definitions directly in
AGENTS.md. This increases the always-injected instruction surface; a linked glossary offers focused definitions that other surfaces can reference.
Runtime middleware, interceptors, and providers do not address this contributor-instruction need.
Investigation
CONTRIBUTING.md already separates triage, technical validation, human acceptance, and direct-request phase authorization. Its Label Discovery section requires inspecting current label descriptions. AGENTS.md and the PR creation/review skills also describe acceptance requirements. The proposal should consolidate terminology while preserving these rules and their existing exceptions.
Activity
purp commentedon Nov 4, 2026
Candidate terminology inventory from
AGENTS.md,CONTRIBUTING.md, contributor skills under.agents/skills/, and public skills underskills/, including their supporting references. These are terms to consider, not proposed policy changes or approved definitions. Grouped phrases may belong in one entry with aliases rather than separate definitions.1. Issue disposition and authority — highest priority
Sources: CONTRIBUTING — Issue Workflow, triage-issue, build-from-issue.
2. Actors, permissions, and review gates
Sources: CONTRIBUTING — First-Time Contributors, create-github-pr, AGENTS — Pull Requests.
3. Intake, evidence, and proposed work
Sources: create-github-issue, create-spike, create-rfc.
4. Triage queue and local action records
Sources: review-triage-queue, apply-triage-action, report template.
5. Contribution scope and verification
Sources: CONTRIBUTING — Pull Requests, CONTRIBUTING — DCO, build-from-issue, Windows build skill.
6. Agent instructions and documentation authority
Sources: AGENTS — Skills, sync-agent-infra, CONTRIBUTING — Agent Skills.
7. Security review and disclosure
Sources: create-security-advisory, review-security-issue, fix-security-issue, AGENTS — Security.
8. Release and operational vocabulary
Sources: release-openshell, release-captain, test-release-canary, sbom.
9. Product terms found in public skills — consider links to existing product definitions
Sources: openshell-cli, generate-sandbox-policy, debug-inference, debug-openshell-cluster, helm-dev-environment.
AGENTS.mdlogging guidance.Suggested first pass: define the authority and disposition terms in groups 1–2, plus acceptance criteria, evidence categories, local triage dispositions, verification outcomes, and sign-off versus signing. Keep the remaining groups as a candidate backlog. For product and specialized technical terms, reuse stable links to their existing authoritative definitions wherever possible so this work does not create another competing glossary.
jyotir07 commentedon Nov 4, 2026
Hey @purp I'd like to work on this issue. Would it be okay if I picked it up and submitted a PR? Thanks! :)
[-]docs: add a canonical glossary for contributor and agent terminology[/-][+]docs: Factor contributor and agent terminology out of docs and skills into a canonical glossary[/+]