From bf7614750af3609d6910cd14b659c09ac816349c Mon Sep 17 00:00:00 2001 From: Hongming Wang Date: Wed, 15 Apr 2026 21:13:04 -0700 Subject: [PATCH] docs(glossary): add terminology disambiguation table (closes #320) CI fully green (all 6 checks pass). Docs-only: adds docs/glossary.md, links from README.md and CLAUDE.md. Closes #320. --- CLAUDE.md | 5 +++++ README.md | 1 + docs/glossary.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+) create mode 100644 docs/glossary.md diff --git a/CLAUDE.md b/CLAUDE.md index 2576a877..7c463329 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,6 +14,11 @@ overlap / differentiation / terminology-collision notes. Cross-referenced from `PLAN.md` and `README.md`; it's the canonical starting point for "what else is out there." +When a term is ambiguous across projects (harness / workspace / plugin / +flow / crew / component), consult **`docs/glossary.md`** for how we use +it vs. ecosystem neighbors — authoritative disambiguation table, kept in +sync with `docs/ecosystem-watch.md`. + ## SaaS ops When rotating SaaS credentials (Fly / Neon / Upstash / envelope key), read diff --git a/README.md b/README.md index 477e04f5..1ebc3b1f 100644 --- a/README.md +++ b/README.md @@ -285,6 +285,7 @@ Then open `http://localhost:3000`: - [Canvas UI](./docs/frontend/canvas.md) - [Local Development](./docs/development/local-development.md) - [Ecosystem Watch](./docs/ecosystem-watch.md) — adjacent projects we track (Holaboss, Hermes, gstack, …) +- [Glossary](./docs/glossary.md) — how we use "harness", "workspace", "plugin", "flow" vs. ecosystem neighbors ## Current Scope diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 00000000..ac797a73 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,48 @@ +# Glossary — Molecule AI terminology vs. ecosystem neighbors + +The agent-infra ecosystem has coalesced around a common vocabulary that +nevertheless means different things in different projects. This page +defines how Molecule AI uses each term and flags the conflicts you're +most likely to hit when reading adjacent documentation. + +Cross-referenced from +[`docs/ecosystem-watch.md`](./ecosystem-watch.md) — when a new project +lands in the watch list with a colliding term, add a row here. + +## Core terms + +| Term | What we mean | What others mean | +|------|--------------|------------------| +| **harness** | The Claude Code execution environment: `~/.claude/settings.json`, hooks, skills, MCP servers, the surrounding CLI. The layer *around* the agent that enforces behavior before tool calls fire. | **OpenHarness** (`HKUDS/OpenHarness`): a research framework wrapper for studying agent internals — closer to a probe than an enforcement layer. | +| **workspace** | An isolated Docker container running one agent with a role, git state, hook pipeline, runtime image, and per-workspace bearer token. Long-lived — a workspace is provisioned once and stays up. | **Paperclip**: closer to "employee" (a persona with memory). **Hermes**: closer to "project" (a unit of work scoped by time). In Molecule, persona = role, unit of work = task/delegation. | +| **plugin** | A directory under `plugins/` packaging one or more skills or an MCP server wrapper, installable per-workspace via `POST /workspaces/:id/plugins`. Governed by `plugin.yaml`. | **Langflow**: a visual UI node / component in a flowchart. **CrewAI**: a Python-importable callable registered as a capability. | +| **agent** | A persistent containerized workspace running continuously — an identity with memory, a role, and a schedule. Not a one-shot invocation. | Most frameworks (AutoGPT, LangChain agents, OpenAI Assistants): a stateless function-call loop. No persistence between invocations unless explicitly checkpointed. | +| **flow** | A task execution within a workspace — a request enters, the agent runs tools, emits a response, logs activity. No explicit graph abstraction. | **Langflow**: a directed graph of nodes you author visually. **LangGraph**: a stateful graph of callable nodes. Our "flow" is an imperative timeline, not a graph. | +| **team** | A named cluster of workspaces under a PM (org template `expand_team`). Used for role grouping in Canvas. | **CrewAI**: a "crew" is a sequence of agents that pass a task through a declared order. Our "team" is an org-chart abstraction, not an execution order. | +| **skill** | A directory with `SKILL.md` that an agent invokes via the `Skill` tool. Skills are documentation + optional scripts that teach an agent a recipe. | **Anthropic Skills API**: nearly identical. **CrewAI tool**: closer to our plugin's MCP tool, not our skill. | +| **channel** | An outbound/inbound social integration (Telegram, Slack, …) per-workspace, wired in `workspace_channels`. | Slack's "channel": the container for messages. We use "channel" for the adapter + credentials, not the conversation itself. | +| **runtime** | The execution engine image tag for a workspace: one of `langgraph`, `claude-code`, `openclaw`, `crewai`, `autogen`, `deepagents`, `hermes`. | **LangGraph runtime**: the Python process running the graph. We use "runtime" for the Docker image + adapter pairing, not the inner process. | + +## Near-miss terms + +These don't appear in the table above because we don't use them in the +same sense as the reference project — flagged so you don't confuse the +two: + +- **crew** (CrewAI) — we don't use this term; the analogue is **team**. +- **tool** — a LangChain `@tool`-decorated callable, shared vocabulary with most frameworks. No conflict, but "skill" is the user-facing abstraction an agent picks up from `SKILL.md`; "tool" is the thing under the hood. +- **component** (Langflow) — no analogue. We have **plugin** (role-level), **skill** (agent-recipe-level), and **adapter** (runtime-level). A Langflow "component" is visual; ours is structural. +- **pipeline** — overloaded in our repo: CI pipeline, ingestion pipeline, etc. Always use the qualifier. + +## When to update this file + +- A project enters `docs/ecosystem-watch.md` with a term that collides with ours → add a row. +- We rename an internal term (e.g., "workspace" to "agent") → update **every** row that references it, update `CLAUDE.md`, update `README.md`, update `docs/architecture.md`. +- A user reports confusion reading a cross-project tutorial → add a row with the confusing term. + +## Cross-references + +- [`README.md`](../README.md) — top-level stack description. +- [`CLAUDE.md`](../CLAUDE.md) — operational vocabulary for agents in this repo. +- [`docs/ecosystem-watch.md`](./ecosystem-watch.md) — source of truth for adjacent-project claims. +- [`docs/architecture.md`](./architecture.md) — deeper definitions for workspace, canvas, platform.