From f19ca4202c2ae20dfae78133e8654a8b9704775f Mon Sep 17 00:00:00 2001 From: Suleiman Shahbari Date: Fri, 26 Jun 2026 22:29:01 +0300 Subject: [PATCH] docs: refresh root README and Architecture for the full shipped package set The root README still listed only @gemstack/ai-sdk, called the rest of the family "planned", and showed a stale 0.1.0 version. All five packages have shipped, so: - list all five (ai-sdk, ai-skills, ai-autopilot, ai-mcp, mcp) with correct versions, descriptions, and the dependency layering - add the "which MCP package do I use" guidance so ai-mcp and mcp never read as duplicates - point at examples/ and the changeset flow Architecture.md: mark the family and @gemstack/mcp as shipped, drop the "(later)" marker on mcp, and turn the suggested ship order into the realized one. --- Architecture.md | 17 ++++++++++------- README.md | 41 ++++++++++++++++++++++++++++++++++------- 2 files changed, 44 insertions(+), 14 deletions(-) diff --git a/Architecture.md b/Architecture.md index 1cbf12b..0d4e9e1 100644 --- a/Architecture.md +++ b/Architecture.md @@ -1,6 +1,6 @@ # GemStack Architecture -A shared reference for how GemStack packages are layered and named. This is the working document for design discussion; it will firm up as packages land. +A shared reference for how GemStack packages are layered and named. The AI family (`ai-sdk`, `ai-skills`, `ai-autopilot`, `ai-mcp`) and the standalone `@gemstack/mcp` server framework have all shipped; the design rationale below is kept as the record of why the boundaries are drawn where they are. ## The naming rule @@ -54,7 +54,7 @@ When a candidate does graduate, follow the `@gemstack/ai-sdk` playbook exactly: @gemstack/ai-autopilot orchestration / autonomy (the "director") -> ai-sdk (+ skills) @gemstack/ai-mcp agent <-> MCP bridge (the "adapter") -> ai-sdk ----------------------------------------------------------------------------------- -@gemstack/mcp (later) standalone MCP server framework agent-agnostic, NOT ai-* +@gemstack/mcp standalone MCP server framework agent-agnostic, NOT ai-* ``` ### Dependency direction (the one rule that keeps four packages from becoming a tangle) @@ -124,9 +124,12 @@ The most speculative of the family, so this records direction, not a committed A Stays parked as a design sketch: revisit once `ai-mcp` and `ai-skills` land and real orchestration use cases emerge. Gated on family alignment before code lands. -## Suggested ship order +## Ship order (all shipped) -1. `@gemstack/ai-sdk` (now) -2. `@gemstack/ai-mcp` (first carve-out; cheap, and forces the dependency seam to be proven early) -3. `@gemstack/ai-skills` -4. `@gemstack/ai-autopilot` +The family shipped in the order that proved the dependency seam earliest: + +1. `@gemstack/ai-sdk` (shipped) +2. `@gemstack/ai-mcp` (shipped - first carve-out; cheap, and forced the dependency seam to be proven early) +3. `@gemstack/ai-skills` (shipped) +4. `@gemstack/ai-autopilot` (shipped) +5. `@gemstack/mcp` (shipped - the standalone server framework, a separate graduation off `@rudderjs/mcp`) diff --git a/README.md b/README.md index bf6389b..1d99c64 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,41 @@ # GemStack -A collection of high-quality, framework-agnostic tools. +A collection of high-quality, framework-agnostic tools for building AI applications in Node. -GemStack is shared, community-governed infrastructure built with the [Vike](https://vike.dev) team. Each tool is a standalone, well-tested package that works in any Node app and composes cleanly with the others. +GemStack is shared, community-governed infrastructure built with the [Vike](https://vike.dev) team. Each tool is a standalone, well-tested package that works in any Node app and composes cleanly with the others. Packages join GemStack by *graduating* one at a time, when they prove framework-agnostic value, not by bulk-moving a framework's package set in. ## Packages -| Package | Description | Status | +| Package | Description | Version | |---|---|---| -| [`@gemstack/ai-sdk`](./packages/ai-sdk) | AI engine: providers, agents, tools, streaming, middleware, memory, evals, MCP, computer-use | `0.1.0` | +| [`@gemstack/ai-sdk`](./packages/ai-sdk) | The agent runtime: providers, the agent loop, tools, streaming, middleware, structured output, memory, and evals. The engine the rest of the AI family builds on. | `0.3.0` | +| [`@gemstack/ai-skills`](./packages/ai-skills) | Portable capability bundles: load `SKILL.md` skills (instructions + tools + resources) and compose them onto an agent on demand. | `0.1.0` | +| [`@gemstack/ai-autopilot`](./packages/ai-autopilot) | Orchestration: a Supervisor that plans, dispatches subagents (bounded concurrency + budget guardrails), and synthesizes the result. | `0.1.0` | +| [`@gemstack/ai-mcp`](./packages/ai-mcp) | The agent/MCP bridge: consume a remote MCP server's tools as agent tools, and expose an agent as an MCP server. | `0.1.0` | +| [`@gemstack/mcp`](./packages/mcp) | A standalone framework for *authoring* MCP servers: tools, resources, prompts, decorators, OAuth 2.1, a framework-neutral HTTP handler, and a test client. Agent-agnostic. | `0.2.0` | -More layers are planned under the same scheme: `@gemstack/ai-skills`, `@gemstack/ai-autopilot`, `@gemstack/ai-mcp`. +### How they fit together -`@gemstack/ai-sdk` is the pilot package, spun out of Rudder's mature `@rudderjs/ai` (v1.17.x) and re-versioned under the GemStack umbrella, while `@rudderjs/ai` continues as a thin deprecated re-export. +``` +@gemstack/ai-sdk agent runtime (the "verbs") +@gemstack/ai-skills capability bundles (the composable "nouns") -> ai-sdk +@gemstack/ai-autopilot orchestration / autonomy (the "director") -> ai-sdk (+ skills) +@gemstack/ai-mcp agent <-> MCP bridge (the "adapter") -> ai-sdk +----------------------------------------------------------------------------------- +@gemstack/mcp standalone MCP server framework agent-agnostic, not ai-* +``` + +The `ai-` prefix means **"depends on the agent runtime."** `skills`, `autopilot`, and `ai-mcp` all depend on `ai-sdk`; `ai-sdk` depends on none of them, and nothing depends "up." A package about AI that is agent-agnostic (like `@gemstack/mcp`) is a peer of the family, not a member of it. + +See [`Architecture.md`](./Architecture.md) for the full layering, naming rule, and graduation policy. + +### Which MCP package do I use? + +The two MCP packages point in opposite directions, so they are never duplicates: + +> **Exposing an existing agent?** Use [`@gemstack/ai-mcp`](./packages/ai-mcp). It makes an agent speak MCP, or feeds remote MCP tools into one. +> +> **Authoring a server from scratch** (tools / resources / prompts / auth)? Use [`@gemstack/mcp`](./packages/mcp). A full server framework, with no agent involved. ## Development @@ -24,7 +47,11 @@ pnpm typecheck pnpm test ``` -This is a pnpm + Turborepo + Changesets monorepo. See [`.changeset/README.md`](./.changeset/README.md) for the release flow. +This is a pnpm + Turborepo + Changesets monorepo. Runnable examples live under [`examples/`](./examples) (e.g. [`examples/mcp-quickstart`](./examples/mcp-quickstart)). See [`.changeset/README.md`](./.changeset/README.md) for the release flow. + +## Origin + +The AI family was spun out of Rudder's mature `@rudderjs/ai` (v1.17.x) and re-versioned under the GemStack umbrella; `@gemstack/mcp` is the graduation of `@rudderjs/mcp`. The old `@rudderjs/*` names continue as thin deprecated re-exports. ## Governance