From af5643d4e9a80630bd1b18873499f7298b610929 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Wed, 25 Feb 2026 13:23:45 +0000 Subject: [PATCH 1/2] docs: clarify create-expert as a published registry expert Update README and docs to explain that create-expert is a published Expert on the Perstack registry, resolved automatically by the CLI without a local perstack.toml. Add E2E test to verify create-expert resolves from the registry and completes a run. Co-Authored-By: Claude Opus 4.6 --- README.md | 2 +- docs/README.md | 2 +- docs/getting-started/walkthrough.md | 2 +- docs/guides/rapid-prototyping.md | 2 +- docs/index.md | 2 +- e2e/perstack-cli/create-expert.test.ts | 22 ++++++++++++++++++++++ 6 files changed, 27 insertions(+), 5 deletions(-) create mode 100644 e2e/perstack-cli/create-expert.test.ts diff --git a/README.md b/README.md index 69994e55..527dcbae 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ A game built with these commands: [demo-dungeon-crawler](https://github.com/pers ## How it works -`create-expert` generates a `perstack.toml` that defines a team of micro-agents. Run it with `npx perstack start create-expert`. Each agent has a single responsibility and its own context window. Complex tasks are broken down and delegated to specialists. +`create-expert` is a published Expert on the [Perstack registry](https://platform.perstack.ai/). It generates a `perstack.toml` that defines a team of micro-agents. No local config file is needed — the CLI resolves `create-expert` from the registry automatically. Each agent has a single responsibility and its own context window. Complex tasks are broken down and delegated to specialists. ```toml [experts."ai-gaming"] diff --git a/docs/README.md b/docs/README.md index f54cf98b..2ae8f966 100644 --- a/docs/README.md +++ b/docs/README.md @@ -35,7 +35,7 @@ Collaborate with `pro-trainer` for professional training menus. delegates = ["pro-trainer"] ``` -Or generate one interactively: +Or generate one interactively using [`create-expert`](https://platform.perstack.ai/), a published Expert on the Perstack registry: ```bash npx perstack start create-expert "Create a fitness assistant that delegates to a pro trainer" diff --git a/docs/getting-started/walkthrough.md b/docs/getting-started/walkthrough.md index 7242246d..242608ae 100644 --- a/docs/getting-started/walkthrough.md +++ b/docs/getting-started/walkthrough.md @@ -23,7 +23,7 @@ Generate an Expert definition interactively: npx perstack start create-expert "Create a fitness assistant that delegates to a pro trainer" ``` -`create-expert` does more than scaffold a file — it: +`create-expert` is a published Expert on the [Perstack registry](https://platform.perstack.ai/) — no local config file is needed. The CLI resolves it from the registry automatically. It does more than scaffold a file — it: - generates Expert definitions in `perstack.toml` based on your description - tests them against real-world scenarios - analyzes execution history and output to evaluate the definitions diff --git a/docs/guides/rapid-prototyping.md b/docs/guides/rapid-prototyping.md index 655903c7..4222b968 100644 --- a/docs/guides/rapid-prototyping.md +++ b/docs/guides/rapid-prototyping.md @@ -46,7 +46,7 @@ npx perstack start reviewer "Review this login handler" ## From idea to agent in one command -Writing TOML by hand works, but there's a faster way. `create-expert` is a published Expert that generates Expert definitions from natural language descriptions — it's itself an Expert that builds other Experts. +Writing TOML by hand works, but there's a faster way. `create-expert` is a published Expert on the [Perstack registry](https://platform.perstack.ai/) that generates Expert definitions from natural language descriptions — it's itself an Expert that builds other Experts. No local config is needed; the CLI resolves it from the registry automatically. ```bash npx perstack start create-expert "A code review assistant that checks for security vulnerabilities, suggests fixes, and explains the reasoning behind each finding" diff --git a/docs/index.md b/docs/index.md index 7962daf1..485525fa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ Define AI agents as **Experts** in natural language. Execute them with determini Perstack is an open-source runtime for executing AI agents defined as Experts. Define behavior in TOML, run from the CLI or embed in your application. ```bash -# Generate an Expert interactively +# Generate an Expert using create-expert (a published Expert on the Perstack registry) npx perstack start create-expert "Create a code-reviewer that delegates to a style-checker" # Run it diff --git a/e2e/perstack-cli/create-expert.test.ts b/e2e/perstack-cli/create-expert.test.ts new file mode 100644 index 00000000..f79a5694 --- /dev/null +++ b/e2e/perstack-cli/create-expert.test.ts @@ -0,0 +1,22 @@ +import { describe, expect, it } from "bun:test" +import { assertEventSequenceContains } from "../lib/assertions.js" +import { runCli, withEventParsing } from "../lib/runner.js" + +const LLM_TIMEOUT = 120000 + +describe("Published create-expert", () => { + it( + "should resolve from registry and complete a run", + async () => { + const cmdResult = await runCli(["run", "create-expert", "hello"], { + timeout: LLM_TIMEOUT, + }) + const result = withEventParsing(cmdResult) + expect(result.exitCode).toBe(0) + expect(assertEventSequenceContains(result.events, ["startRun", "completeRun"]).passed).toBe( + true, + ) + }, + LLM_TIMEOUT, + ) +}) From af87cadfb623d14ba2ef1c7efdc9987938eb0470 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Wed, 25 Feb 2026 13:26:36 +0000 Subject: [PATCH 2/2] fix: replace platform.perstack.ai URLs with perstack.ai Co-Authored-By: Claude Opus 4.6 --- README.md | 2 +- docs/README.md | 4 ++-- docs/getting-started/walkthrough.md | 2 +- docs/guides/rapid-prototyping.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 527dcbae..0a8a70a9 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ A game built with these commands: [demo-dungeon-crawler](https://github.com/pers ## How it works -`create-expert` is a published Expert on the [Perstack registry](https://platform.perstack.ai/). It generates a `perstack.toml` that defines a team of micro-agents. No local config file is needed — the CLI resolves `create-expert` from the registry automatically. Each agent has a single responsibility and its own context window. Complex tasks are broken down and delegated to specialists. +`create-expert` is a published Expert on the [Perstack registry](https://perstack.ai/). It generates a `perstack.toml` that defines a team of micro-agents. No local config file is needed — the CLI resolves `create-expert` from the registry automatically. Each agent has a single responsibility and its own context window. Complex tasks are broken down and delegated to specialists. ```toml [experts."ai-gaming"] diff --git a/docs/README.md b/docs/README.md index 2ae8f966..dc2f2bd1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,7 +5,7 @@ title: "Perstack: The Declarative Runtime for Agentic AI" Define AI agents as **Experts** in natural language. Execute them with deterministic, event-derived tracking. Each Expert runs in its own isolated context — no shared state, no prompt bloat, full execution history. - [Getting Started →](./getting-started/walkthrough.md) -- [Browse Registry →](https://platform.perstack.ai/) +- [Browse Registry →](https://perstack.ai/) ## What Perstack Solves @@ -35,7 +35,7 @@ Collaborate with `pro-trainer` for professional training menus. delegates = ["pro-trainer"] ``` -Or generate one interactively using [`create-expert`](https://platform.perstack.ai/), a published Expert on the Perstack registry: +Or generate one interactively using [`create-expert`](https://perstack.ai/), a published Expert on the Perstack registry: ```bash npx perstack start create-expert "Create a fitness assistant that delegates to a pro trainer" diff --git a/docs/getting-started/walkthrough.md b/docs/getting-started/walkthrough.md index 242608ae..0e01dd88 100644 --- a/docs/getting-started/walkthrough.md +++ b/docs/getting-started/walkthrough.md @@ -23,7 +23,7 @@ Generate an Expert definition interactively: npx perstack start create-expert "Create a fitness assistant that delegates to a pro trainer" ``` -`create-expert` is a published Expert on the [Perstack registry](https://platform.perstack.ai/) — no local config file is needed. The CLI resolves it from the registry automatically. It does more than scaffold a file — it: +`create-expert` is a published Expert on the [Perstack registry](https://perstack.ai/) — no local config file is needed. The CLI resolves it from the registry automatically. It does more than scaffold a file — it: - generates Expert definitions in `perstack.toml` based on your description - tests them against real-world scenarios - analyzes execution history and output to evaluate the definitions diff --git a/docs/guides/rapid-prototyping.md b/docs/guides/rapid-prototyping.md index 4222b968..ca6da3c6 100644 --- a/docs/guides/rapid-prototyping.md +++ b/docs/guides/rapid-prototyping.md @@ -46,7 +46,7 @@ npx perstack start reviewer "Review this login handler" ## From idea to agent in one command -Writing TOML by hand works, but there's a faster way. `create-expert` is a published Expert on the [Perstack registry](https://platform.perstack.ai/) that generates Expert definitions from natural language descriptions — it's itself an Expert that builds other Experts. No local config is needed; the CLI resolves it from the registry automatically. +Writing TOML by hand works, but there's a faster way. `create-expert` is a published Expert on the [Perstack registry](https://perstack.ai/) that generates Expert definitions from natural language descriptions — it's itself an Expert that builds other Experts. No local config is needed; the CLI resolves it from the registry automatically. ```bash npx perstack start create-expert "A code review assistant that checks for security vulnerabilities, suggests fixes, and explains the reasoning behind each finding"