From 9009f324ec360e5fc8107ccff4627d9db3b48089 Mon Sep 17 00:00:00 2001 From: Suleiman Shahbari Date: Sat, 4 Jul 2026 04:48:34 +0300 Subject: [PATCH] docs: document the compose personas, --compose-extensions, and the publish gate ai-autopilot README named a nonexistent universalOrmModeler persona and called the default stack Vike + universal-orm; the built-in is dataModeler (Prisma) and the canonical default is Vike + Prisma. Fix both, and document the opt-in vikeExtensionPersonas composer set. framework README omitted --compose-extensions and never explained the composer path or the publish gate; add the flag and a short section. Also refresh the --help text, which described the flag as vike-auth only. Closes #200 --- .changeset/help-compose-extensions-full-set.md | 7 +++++++ packages/ai-autopilot/README.md | 18 ++++++++++++++++-- packages/framework/README.md | 13 +++++++++++++ packages/framework/src/cli.ts | 7 ++++--- 4 files changed, 40 insertions(+), 5 deletions(-) create mode 100644 .changeset/help-compose-extensions-full-set.md diff --git a/.changeset/help-compose-extensions-full-set.md b/.changeset/help-compose-extensions-full-set.md new file mode 100644 index 0000000..5065527 --- /dev/null +++ b/.changeset/help-compose-extensions-full-set.md @@ -0,0 +1,7 @@ +--- +'@gemstack/framework': patch +--- + +Fix the `--compose-extensions` help text to name the full composer set + +The `framework --help` output described `--compose-extensions` as composing "vike-auth for auth" only, but the flag frames the agent with the whole vike-* composer set: auth, the universal-orm data layer, rbac, crud/admin, and themes/layouts. The help text now names them accurately. diff --git a/packages/ai-autopilot/README.md b/packages/ai-autopilot/README.md index 52ada56..d232961 100644 --- a/packages/ai-autopilot/README.md +++ b/packages/ai-autopilot/README.md @@ -43,12 +43,12 @@ Each stage is a plain function, so you mix LLM and deterministic logic freely: ## Personas — the stack-aware layer The Supervisor is stack-agnostic. **Personas** add the opinionated knowledge that -makes autopilot know the GemStack stack (Vike + universal-orm) instead of +makes autopilot know the GemStack stack (Vike + Prisma) instead of guessing. A persona is *data*: a name, a one-line role, a system-prompt fragment, and the skills/tools it brings (composed over [`@gemstack/ai-skills`](https://github.com/gemstack-land/gemstack/tree/main/packages/ai-skills)). Three are built in: `vikePageBuilder` (Vike `+` file conventions, renderer-agnostic), -`universalOrmModeler` (schema-first data, derived migrations), and +`dataModeler` (schema-first data on Prisma, derived migrations), and `uiIntentDesigner` — the "declare intent, decouple implementation" guardrail that expresses UI as intent so an AI can't hardcode the wrong markup. @@ -70,6 +70,20 @@ Define your own with `definePersona({ name, role, systemPrompt, skills?, tools? or materialize a single persona into an agent with `personaAgent(persona)`. Because a persona is data, it can be inspected and listed without building an agent first. +### Composing vike-* extensions (opt-in) + +For a Vike app, an opt-in set swaps the hand-rolled default for personas that +**compose** the vike-* extensions instead of reinventing them: `vikeAuthComposer` +(vike-auth for identity/sessions), `vikeDataModeler` (the universal-orm data layer), +`vikeRbacComposer` (vike-rbac roles/permissions), `vikeCrudComposer` +(vike-crud/vike-admin for schema-derived CRUD + admin UI), and `vikeShellComposer` +(vike-themes/vike-layouts for styling and the app shell), plus the shared +`uiIntentDesigner` guardrail. They ship as the `vikeExtensionPersonas` array. + +This path is opt-in because the vike-* packages currently resolve only inside the +vike-data workspace (they are not published to npm), so the default `stackPersonas` +path stays publish-safe. `@gemstack/framework` exposes it as `--compose-extensions`. + ## Runner — the pluggable execution seam Autopilot builds and runs an app somewhere. A **`Runner`** boots an isolated diff --git a/packages/framework/README.md b/packages/framework/README.md index 8c58556..544acc1 100644 --- a/packages/framework/README.md +++ b/packages/framework/README.md @@ -66,6 +66,7 @@ framework --fake Offline demo (no CLI, no model, deterministic). --cwd Workspace the agent builds in (default: cwd). --model Model to pass through to the wrapped agent. --scope How much app to build (default: full). + --compose-extensions Compose the vike-* extensions instead of hand-rolling them (Vike-only, opt-in). --deploy Narrate a deploy decision (e.g. cloudflare, dokploy). --port Dashboard port (default: 4477). --no-dashboard Run headless. @@ -75,6 +76,18 @@ framework --fake Offline demo (no CLI, no model, deterministic). The live path needs the Claude Code CLI installed (`claude` on `PATH`). The `--fake` path needs neither a CLI nor a model, so it is what CI runs. +## Composing vike-* extensions + +By default the agent hand-rolls auth and models data with Prisma, a fully +publish-safe stack. Pass `--compose-extensions` (Vike-only) to instead frame the +agent with the **composer personas**: compose vike-auth for identity, the +universal-orm data layer for domain data, vike-rbac for roles/permissions, +vike-crud/vike-admin for schema-derived CRUD + admin UI, and vike-themes/vike-layouts +for styling and the app shell, rather than reinventing each. It is opt-in because +those vike-* packages currently resolve only inside the vike-data workspace, so the +default path is the one that stays publishable. See `@gemstack/ai-autopilot`'s +`vikeExtensionPersonas`. + ## Status MVP (#166): the driver seam, the Claude Code driver, the CLI, and the dashboard, diff --git a/packages/framework/src/cli.ts b/packages/framework/src/cli.ts index be778e3..e294e69 100644 --- a/packages/framework/src/cli.ts +++ b/packages/framework/src/cli.ts @@ -34,9 +34,10 @@ Options: --cwd Workspace the agent builds in (default: current directory). --model Model to pass through to the wrapped agent. --scope How much app to build (default: full). - --compose-extensions Compose the vike-* extensions (vike-auth for auth) instead - of hand-rolling them. Vike-only; extensions resolve in the - vike-data workspace (default: off, hand-rolled + Prisma). + --compose-extensions Compose the vike-* extensions (auth, data, rbac, crud, + themes/layouts) instead of hand-rolling them. Vike-only; + extensions resolve in the vike-data workspace + (default: off, hand-rolled + Prisma). --max-passes Full-fledged loop pass budget (default: 5). --permission-mode Claude Code permission mode: default | acceptEdits | bypassPermissions | plan (default: acceptEdits).