Skip to content

Commit 93fbd51

Browse files
github-actions[bot]Copilot
github-actions[bot]
and
Copilot
committed
Add link-checker workflow source and Glossary Maintainer workflow
Phase 1 - Consistency Fix: - Added missing workflows/link-checker.md (docs existed but workflow source was missing) Phase 2 - New Workflow: - Added Glossary Maintainer workflow from Peli's Agent Factory - Perfect 100% merge rate (10/10 PRs) in original repository - Generalized for any project with glossary/terminology documentation - Added workflows/glossary-maintainer.md - Added docs/glossary-maintainer.md - Updated README.md with new workflow entry Source: https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/glossary-maintainer.md Blog: https://github.github.com/gh-aw/blog/2026-01-13-meet-the-workflows-documentation/ Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 8828ac8 commit 93fbd51

4 files changed

Lines changed: 652 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ You can use the "/plan" agent to turn the reports into actionable issues which c
4949

5050
- [📖 Regular Documentation Update](docs/update-docs.md) - Update documentation automatically
5151
- [📖 Daily Documentation Updater](docs/daily-doc-updater.md) - Automatically update documentation based on recent code changes and merged PRs
52+
- [📖 Glossary Maintainer](docs/glossary-maintainer.md) - Automatically maintain project glossary based on codebase changes
5253
- [🔗 Link Checker](docs/link-checker.md) - Daily automated link checker that finds and fixes broken links in documentation
5354
- [✨ Code Simplifier](docs/code-simplifier.md) - Automatically simplify recently modified code for improved clarity and maintainability
5455
- [⚡ Daily Progress](docs/daily-progress.md) - Automated daily feature development following a structured roadmap

‎docs/glossary-maintainer.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# 📖 Glossary Maintainer
2+
3+
> For an overview of all available workflows, see the [main README](../README.md).
4+
5+
The [Glossary Maintainer workflow](../workflows/glossary-maintainer.md?plain=1) automatically maintains project glossary or terminology documentation by scanning code changes and keeping technical terms up-to-date.
6+
7+
## Installation
8+
9+
```bash
10+
# Install the 'gh aw' extension
11+
gh extension install github/gh-aw
12+
13+
# Add the workflow to your repository
14+
gh aw add-wizard githubnext/agentics/glossary-maintainer
15+
```
16+
17+
This walks you through adding the workflow to your repository.
18+
19+
You can start a run of this workflow immediately by running:
20+
21+
```bash
22+
gh aw run glossary-maintainer
23+
```
24+
25+
## What It Does
26+
27+
The Glossary Maintainer workflow runs daily on weekdays and:
28+
29+
1. **Scans Recent Changes** - Reviews commits and PRs from the last 24 hours (daily) or 7 days (weekly on Mondays)
30+
2. **Identifies New Terms** - Finds technical terminology, configuration options, and project-specific concepts
31+
3. **Updates Definitions** - Adds new terms or updates existing definitions based on code changes
32+
4. **Maintains Consistency** - Ensures glossary follows existing structure and style
33+
5. **Creates Pull Requests** - Proposes glossary updates for review when new terms are found
34+
35+
## How It Works
36+
37+
### Incremental vs Full Scans
38+
39+
- **Daily (Mon-Fri)**: Incremental scan of last 24 hours
40+
- **Monday**: Full scan of last 7 days for comprehensive review
41+
42+
### What Gets Added
43+
44+
The workflow identifies terms that are:
45+
- Used in user-facing documentation or code
46+
- Project-specific or domain-specific
47+
- Technical terms requiring explanation
48+
- Newly introduced in recent changes
49+
50+
### What Gets Skipped
51+
52+
The workflow avoids adding:
53+
- Generic programming terms
54+
- Self-evident terminology
55+
- Internal implementation details
56+
- Terms only in code comments
57+
58+
## Configuration
59+
60+
This workflow works out of the box and automatically:
61+
- Locates your glossary file (common paths: `docs/glossary.md`, `docs/reference/glossary.md`, `GLOSSARY.md`)
62+
- Follows your existing glossary structure and style
63+
- Maintains alphabetical or categorical organization
64+
- Uses cache memory to avoid duplicate work
65+
66+
You can edit the workflow to customize:
67+
- The glossary file path if it's in a non-standard location
68+
- The scanning timeframe (daily vs weekly)
69+
- The PR title prefix and labels
70+
71+
After editing, run `gh aw compile` to apply your changes.
72+
73+
## What it reads from GitHub
74+
75+
- Recent commits and their diffs
76+
- Merged pull requests from the specified timeframe
77+
- PR descriptions and comments
78+
- Code changes that introduce new terminology
79+
80+
## What it creates
81+
82+
- Pull requests with glossary updates
83+
- Cache memory of processed commits to avoid duplicates
84+
85+
## When it runs
86+
87+
- **Daily on weekdays** (incremental scan of last 24 hours)
88+
- **Mondays** (full scan of last 7 days)
89+
- **Manually** via workflow_dispatch
90+
91+
## Permissions required
92+
93+
- `contents: read` - To read repository files
94+
- `issues: read` - To review issue discussions
95+
- `pull-requests: read` - To analyze PR descriptions
96+
- `actions: read` - To check workflow runs
97+
98+
## Benefits
99+
100+
1. **Automatic maintenance**: Keeps terminology documentation current without manual tracking
101+
2. **Consistency**: Ensures definitions stay aligned with code changes
102+
3. **Accessibility**: Helps new contributors understand project-specific terms
103+
4. **Time savings**: Eliminates manual glossary updates
104+
5. **Historical context**: Uses cache memory to track what's been processed
105+
106+
## Example Output
107+
108+
When the workflow finds new terms, it creates a PR like:
109+
110+
**Title:** `[docs] Update glossary - daily scan`
111+
112+
**Body:**
113+
```markdown
114+
### Glossary Updates
115+
116+
**Scan Type**: Incremental (daily)
117+
118+
**Terms Added**:
119+
- **Safe Outputs**: Security mechanism for controlling workflow write operations
120+
- **Cache Memory**: Persistent storage for workflow state across runs
121+
122+
**Terms Updated**:
123+
- **Frontmatter**: Updated to include new engine configuration options
124+
125+
**Changes Analyzed**:
126+
- Reviewed 5 commits from last 24 hours
127+
- Analyzed 2 merged PRs
128+
- Processed 1 new feature (cache-memory tool)
129+
130+
**Related Changes**:
131+
- abc1234: Add cache-memory tool support
132+
- PR #123: Implement safe-outputs validation
133+
```
134+
135+
## Source and Success Rate
136+
137+
This workflow is adapted from Peli's Agent Factory, where it achieved:
138+
139+
- **100% merge rate** (10 out of 10 PRs merged)
140+
- **Perfect accuracy** in identifying relevant terminology
141+
- **High value** for documentation consistency
142+
143+
Source: [Glossary Maintainer](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/glossary-maintainer.md) from [github/gh-aw](https://github.com/github/gh-aw)
144+
145+
Read more: [Meet the Workflows: Continuous Documentation](https://github.github.com/gh-aw/blog/2026-01-13-meet-the-workflows-documentation/)
146+
147+
## Generalization Notes
148+
149+
This workflow has been adapted from the gh-aw repository to work with any project:
150+
151+
- **Flexible glossary location**: Automatically finds glossary files in common locations
152+
- **Structure-agnostic**: Works with alphabetical or categorical organization
153+
- **No external dependencies**: Doesn't require Serena or project-specific tools
154+
- **Universal terminology**: Identifies terms based on usage patterns, not hard-coded lists
155+
156+
## Use Cases
157+
158+
This workflow is valuable for:
159+
160+
- **Open source projects** with growing terminology
161+
- **Technical documentation** that needs to stay synchronized with code
162+
- **API projects** with evolving configuration options
163+
- **Developer tools** with CLI commands and options
164+
- **Frameworks** with specialized concepts and patterns
165+
166+
## Future Enhancements
167+
168+
Possible improvements:
169+
- Suggest related terms when adding new definitions
170+
- Detect inconsistent terminology usage across documentation
171+
- Generate glossary if one doesn't exist
172+
- Link term usage to specific code locations
173+
- Track term popularity and usage frequency

0 commit comments

Comments
 (0)