Skip to content

docs: refresh root README and Architecture for the full shipped package set #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
suleimansh merged 1 commit into from
Jun 26, 2026
Merged

docs: refresh root README and Architecture for the full shipped package set #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 10 additions & 7 deletions Architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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`)
41 changes: 34 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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

Expand Down
Loading