docs(glossary): add terminology disambiguation table (#320) - #331
Merged
Merged
Conversation
The agent-infra ecosystem reuses the same words for different concepts. OpenHarness, Langflow, CrewAI, Paperclip, and Hermes have all landed in docs/ecosystem-watch.md with colliding terminology — harness, workspace, plugin, agent, flow, crew, component — and a user reading cross-project tutorials has no single place to check "did they mean the same thing?" Added docs/glossary.md with a 9-row core-terms table (harness, workspace, plugin, agent, flow, team, skill, channel, runtime) and a near-miss section for terms we intentionally don't use (crew, component, tool, pipeline). Cross-referenced from README.md "Documentation Map" section and from CLAUDE.md "Ecosystem Context" section so agents reading this repo know to check it. Update rule for future maintainers included in the file: any new entry in docs/ecosystem-watch.md that introduces a conflicting term should add a row here; any internal rename of a term should update every row that references it. Closes #320 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
HongmingWang-Rabbit
left a comment
HongmingWang-Rabbit
left a comment
Contributor
Author
There was a problem hiding this comment.
Dev Lead Code Review — ✅ Approved
Issue: #320 — Terminology disambiguation table
What I checked
docs/glossary.md(new): Clean, well-structured table. All 8 core terms (harness, workspace, plugin, agent, flow, team, skill, channel, runtime) have accurate Molecule vs. ecosystem definitions. The near-miss section for crew/tool/component/pipeline is a good catch — these cause real confusion in cross-project onboarding. ✅CLAUDE.mdupdate: The pointer todocs/glossary.mdis well-placed in the intro context, will catch agents before they hit a confusing term. ✅README.mdupdate: Added to the correct docs index section alongside ecosystem-watch. ✅- Cross-references: All four cross-refs in the glossary footer point to real files. ✅
- No stale definitions: Spot-checked 'workspace', 'skill', and 'channel' against
docs/architecture.mdmental model — consistent. ✅
Verdict: Merge. Clean docs hygiene, no risks.
3 tasks
HongmingWang-Rabbit
pushed a commit
that referenced
this pull request
Jun 12, 2026
…T-Instance-4) Per CTO directive 2026-05-20 and task #347 (disabled GitHub-mirror push fleet-wide), .github/workflows/ on molecule-core is dead — Gitea Actions reads .gitea/workflows/ exclusively (memory: reference_molecule_core_actions_gitea_only), and GitHub Actions has had no real push activity since 2026-05-06 (the only post-2026-05-06 runs are dynamic CodeQL re-runs on frozen pre-suspension PRs). Empirical validation: - 24 files total in .github/workflows/. - 23 have same-name siblings in .gitea/workflows/ (port carries "Ported from .github/workflows/X on 2026-05-11 per RFC internal#219" header on most files). - 1 .github-only file: canary-staging.yml — already ported to .gitea/workflows/staging-smoke.yml on 2026-05-11 per the same RFC, Hongming directive renamed canary→smoke. Verified via header comment in staging-smoke.yml. - Last GitHub-side push event: 2026-05-06T07:06:12Z (pre-suspension). - All 24 .github/workflows/* files removed. Tooling updates needed (load-bearing): - tools/branch-protection/check_name_parity.sh: hard-coded $REPO_ROOT/.github/workflows path → switched to .gitea/workflows. Pre-existing parity findings (3x Analyze CodeQL names absent from any workflow file) are unchanged — that drift exists pre-PR and is out-of-scope (file as follow-up). - tools/branch-protection/test_check_name_parity.sh: synthetic test fixtures now create .gitea/workflows/ instead of .github/workflows/. All 6 unit tests pass after change. - .gitea/workflows/lint-required-workflows-docker-host-pinned.yml: dropped '.github/workflows/**' from path-filter triggers + dropped '.github/workflows' from the python directory-walk loop (the isdir-check would have made this a no-op cleanly, but pruning reflects current truth). Out-of-scope (NOT touched in this PR): - .github/CODEOWNERS, .github/dependabot.yml, .github/scripts/ remain (task is scoped to .github/workflows/). - COVERAGE_FLOOR.md, workspace/smoke_mode.py, workspace/main.py contain comment references to .github/workflows/* — stale docs string-references only, not behavioral. Separate follow-up. - Provenance comments inside .gitea/workflows/* of the form "Ported from .github/workflows/X on 2026-05-11" are intentionally preserved — useful history. Refs: task #331 (SSOT-Instance-4), task #347 (mirror push disabled), memory reference_molecule_core_actions_gitea_only, memory reference_per_repo_gitea_vs_github_actions_dir, RFC internal#219 §1 (the original 2026-05-11 port sweep).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs-only fix for #320. OpenHarness / Langflow / CrewAI / Paperclip / Hermes have all landed in
docs/ecosystem-watch.mdwith colliding terminology. Add a single table agents and readers can consult.Changes
docs/glossary.md— 9-row core-terms table (harness, workspace, plugin, agent, flow, team, skill, channel, runtime) + near-miss section (crew, component, tool, pipeline).README.md"Documentation Map" section.CLAUDE.md"Ecosystem Context" so agents reading this repo know to check it.Maintenance rule embedded in the file: any new entry in
docs/ecosystem-watch.mdwith a conflicting term adds a row here; any internal rename updates every referencing row.Closes #320