diff --git a/README.md b/README.md index dc5021d..5bb6e4d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ -# corp-v1--glossary +# Corp v1 Glossary -Govern shared terminology in Corp v1 project documentation. \ No newline at end of file +Authoritative global skill for governing terminology in Corp v1 project documentation. + +- Skill: `corp-v1--glossary` +- Default branch: `test` +- Approved by Corp v1 Board member RootAtSkic in Discord message `1539990220320014396` on 2026-08-20. + +Project documentation keeps **Glossary** as its final top-level menu item. Channel skills reference this global skill; it is not copied into each project unless the Board changes the operating model. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..82ec65c --- /dev/null +++ b/SKILL.md @@ -0,0 +1,77 @@ +--- +name: corp-v1--glossary +description: Govern shared terms in Corp v1 project documentation. +version: 1.0.0 +author: Lego (RootAtSkic), Hermes Agent +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [corp-v1, glossary, terminology, documentation] + related_skills: [documentation-docusaurus] +--- + +# Corp v1 Glossary + +This skill governs project terminology. It keeps term definitions out of architecture, scope, delivery, and other domain pages while preserving links from those pages to one authoritative project Glossary. + +## When to Use + +Use this skill when: + +- a Corp v1 page explains what a domain or technical term means; +- the same term may appear in more than one documentation area; +- reviewers disagree about terminology or classification; +- creating or restructuring a project's top-level Glossary area; +- adding, changing, deprecating, or linking a project term. + +Do not use it for ordinary narrative, requirements, architecture decisions, procedures, or API reference that does not define reusable terminology. + +## Documentation Contract + +Every Corp v1 project documentation site has **Glossary** as its final top-level menu item with a dedicated sidebar. The minimum sidebar begins with `Terms`; projects may add alphabetical term pages beneath it when the registry becomes difficult to scan. + +A glossary entry records: + +```text +Term | definition | scope | status | aliases | related terms | authoritative links +``` + +Rules: + +1. Define a term once in Glossary and link to it from domain pages. +2. Keep the definition concise and project-specific; do not paste generic encyclopedia material. +3. State the operational distinction the reader needs. For example, distinguish a deployable C4 container from a code component. +4. Preserve domain evidence in its owning area. Glossary explains the term; Architecture owns architecture facts and decisions, Scope owns product definitions, and Delivery owns implementation procedures. +5. Use stable lowercase anchors or slugs and link every first material use where Docusaurus permits. +6. Record aliases and deprecated wording rather than silently deleting terms that remain in historical records. +7. Mark uncertain or proposed definitions as `Proposed`; only verified/approved definitions are `Adopted`. +8. Avoid circular definitions and definitions that rely on unexplained project jargon. + +## Procedure + +1. Identify the reusable term and the exact sentence that currently explains it. Completion: the candidate is terminology rather than domain evidence or procedure. +2. Search the project's Glossary and domain pages for existing definitions or aliases. Completion: duplicates and contradictions are listed. +3. Add or update one canonical Glossary entry with scope, status, aliases, related terms, and authoritative links. Completion: one stable term anchor or page owns the definition. +4. Replace duplicated explanatory prose with a concise contextual statement and Glossary link. Completion: domain pages retain only facts needed for that page. +5. Validate dedicated navigation, links, Docusaurus build, and deployed rendering using the project's documentation skill. Completion: the Glossary is last in top-level navigation and every changed link resolves. +6. Publish through the project's review and verification workflow. Completion: immutable source readback and deployed-page evidence confirm the term and links. + +## Pitfalls + +1. Turning Glossary into a catch-all reference manual. +2. Moving architecture evidence or decisions out of Architecture. +3. Treating a library as a deployable container because both use the word “package.” +4. Duplicating the same definition across several pages. +5. Adding generic definitions that do not clarify project usage. +6. Renaming historical terminology without aliases or deprecation notes. +7. Placing Glossary anywhere except last in top-level navigation. + +## Verification + +- [ ] Glossary is the final top-level menu item and has a dedicated sidebar. +- [ ] Every changed term has one canonical definition and stable link. +- [ ] Domain pages link rather than repeat glossary-style explanations. +- [ ] Scope, status, aliases, related terms, and authoritative links are present where applicable. +- [ ] Domain-owned evidence and decisions remain in their owning sections. +- [ ] Navigation, links, production build, deployed rendering, and immutable source readback pass.