clawchef 0.1.2 → 0.1.4

package/README.md

@@ -19,6 +19,7 @@ Recipe-driven OpenClaw environment orchestrator.
 - Materializes files into target workspaces.
 - Installs skills.
 - Supports plugin preinstall via `openclaw.plugins[]` and runtime `--plugin` flags.
+- Supports preserving existing OpenClaw state via `--keep-openclaw-state` (skip factory reset).
 - Configures channels with `openclaw channels add`.
 - Supports interactive channel login at the end of execution (`channels[].login: true`) for channels that expose login.
 - Supports remote HTTP orchestration via runtime flags (`--provider remote`) when OpenClaw is reachable via API.
@@ -38,6 +39,12 @@ Run recipe from URL:
 clawchef cook https://example.com/recipes/sample.yaml --provider remote
 ```
 
+Run recipe from GitHub repository root (`recipe.yaml` at repo root):
+
+```bash
+clawchef cook https://github.com/renorzr/loom-plus-recipe
+```
+
 Run recipe from archive (default `recipe.yaml`):
 
 ```bash
@@ -78,6 +85,12 @@ clawchef cook recipes/sample.yaml -s
 Warning: `-s/--silent` suppresses the factory-reset confirmation and auto-chooses force reinstall on version mismatch.
 Use it only in CI/non-interactive flows where destructive reset behavior is expected.
 
+Keep existing OpenClaw state (skip reset and keep current version on mismatch):
+
+```bash
+clawchef cook recipes/sample.yaml --keep-openclaw-state
+```
+
 From-zero OpenClaw bootstrap (recommended):
 
 ```bash
@@ -142,9 +155,9 @@ clawchef scaffold ./my-recipe-project --name meetingbot
 Scaffold output:
 
 - `package.json` with `telegram-api-mock-server` in `devDependencies`
-- `src/recipe.yaml` with `telegram-mock` channel, plugin preinstall, and `workspaces[].assets`
-- `src/<project-name>-assets/{AGENTS.md,IDENTITY.md,SOUL.md,TOOLS.md}`
-- `src/<project-name>-assets/scripts/scheduling.mjs`
+- `recipe.yaml` with `telegram-mock` channel, plugin preinstall, and `workspaces[].assets`
+- `assets/{AGENTS.md,IDENTITY.md,SOUL.md,TOOLS.md}`
+- `assets/scripts/scheduling.mjs`
 - `test/recipe-smoke.test.mjs`
 
 By default scaffold only writes files; it does not run `npm install`.
@@ -188,7 +201,7 @@ Notes:
 
 - `validate()` throws on invalid recipe.
 - `cook()` throws on runtime/configuration errors.
-- `scaffold()` creates `package.json`, `src/recipe.yaml`, `src/<project-name>-assets`, and `test/`.
+- `scaffold()` creates `package.json`, `recipe.yaml`, `assets/`, and `test/`.
 
 ## Variable precedence
 
@@ -212,6 +225,7 @@ If `.env` exists in the directory where `clawchef` is executed, it is loaded bef
 - `https://host/recipe.yaml`
 - `https://host/archive.zip` (loads `recipe.yaml` from archive)
 - `https://host/archive.zip:custom/recipe.yaml`
+- `https://github.com/<owner>/<repo>` (loads `recipe.yaml` from repo root)
 
 Supported archives: `.zip`, `.tar`, `.tar.gz`, `.tgz`.
 

package/dist/api.js

@@ -15,6 +15,7 @@ function normalizeCookOptions(options) {
         allowMissing: Boolean(options.allowMissing),
         verbose: Boolean(options.verbose),
         silent: options.silent ?? true,
+        keepOpenClawState: false,
         provider: options.provider ?? "command",
         remote: options.remote ?? {},
     };

package/dist/cli.js

@@ -77,6 +77,7 @@ export function buildCli() {
         .option("--allow-missing", "Allow unresolved template variables", false)
         .option("--verbose", "Verbose logging", false)
         .option("-s, --silent", "Skip reset confirmation prompt", false)
+        .option("--keep-openclaw-state", "Preserve existing OpenClaw state (skip factory reset)", false)
         .option("--provider <provider>", "Execution provider: command | remote | mock")
         .option("--plugin <npm-spec>", "Preinstall plugin package (repeatable)", (v, p) => p.concat([v]), [])
         .option("--remote-base-url <url>", "Remote OpenClaw API base URL")
@@ -94,6 +95,7 @@ export function buildCli() {
             allowMissing: Boolean(opts.allowMissing),
             verbose: Boolean(opts.verbose),
             silent: Boolean(opts.silent),
+            keepOpenClawState: Boolean(opts.keepOpenclawState),
             provider,
             remote: {
                 base_url: opts.remoteBaseUrl ?? readEnv("CLAWCHEF_REMOTE_BASE_URL"),

package/dist/openclaw/command-provider.d.ts

@@ -2,7 +2,7 @@ import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection } from "../
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 export declare class CommandOpenClawProvider implements OpenClawProvider {
     private readonly stagedMessages;
-    ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean): Promise<EnsureVersionResult>;
+    ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean, keepOpenClawState: boolean): Promise<EnsureVersionResult>;
     factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
     installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
     startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;

package/dist/openclaw/command-provider.js

@@ -221,7 +221,7 @@ function bootstrapRuntimeEnv(bootstrap) {
 }
 export class CommandOpenClawProvider {
     stagedMessages = new Map();
-    async ensureVersion(config, dryRun, silent) {
+    async ensureVersion(config, dryRun, silent, keepOpenClawState) {
         const bin = config.bin ?? "openclaw";
         const installPolicy = config.install ?? "auto";
         const useCmd = commandFor(config, "use_version", { bin, version: config.version });
@@ -272,6 +272,9 @@ export class CommandOpenClawProvider {
         if (installedThisRun) {
             throw new ClawChefError(`OpenClaw version mismatch after install: current ${currentVersion}, expected ${config.version}`);
         }
+        if (keepOpenClawState) {
+            return { installedThisRun: false };
+        }
         const choice = await chooseVersionMismatchAction(currentVersion, config.version, silent);
         if (choice === "ignore") {
             return { installedThisRun: false };

package/dist/openclaw/mock-provider.d.ts

@@ -2,7 +2,7 @@ import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection } from "../
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 export declare class MockOpenClawProvider implements OpenClawProvider {
     private state;
-    ensureVersion(config: OpenClawSection, _dryRun: boolean, _silent: boolean): Promise<EnsureVersionResult>;
+    ensureVersion(config: OpenClawSection, _dryRun: boolean, _silent: boolean, _keepOpenClawState: boolean): Promise<EnsureVersionResult>;
     installPlugin(_config: OpenClawSection, _pluginSpec: string, _dryRun: boolean): Promise<void>;
     factoryReset(_config: OpenClawSection, _dryRun: boolean): Promise<void>;
     startGateway(_config: OpenClawSection, _dryRun: boolean): Promise<void>;

package/dist/openclaw/mock-provider.js

@@ -7,7 +7,7 @@ export class MockOpenClawProvider {
         skills: new Set(),
         messages: new Map(),
     };
-    async ensureVersion(config, _dryRun, _silent) {
+    async ensureVersion(config, _dryRun, _silent, _keepOpenClawState) {
         const policy = config.install ?? "auto";
         const installed = this.state.installedVersions.has(config.version);
         let installedThisRun = false;

package/dist/openclaw/provider.d.ts

@@ -6,7 +6,7 @@ export interface EnsureVersionResult {
     installedThisRun: boolean;
 }
 export interface OpenClawProvider {
-    ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean): Promise<EnsureVersionResult>;
+    ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean, keepOpenClawState: boolean): Promise<EnsureVersionResult>;
     installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
     factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
     startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;

package/dist/openclaw/remote-provider.d.ts

@@ -5,7 +5,7 @@ export declare class RemoteOpenClawProvider implements OpenClawProvider {
     private readonly remoteConfig;
     constructor(remoteConfig: Partial<OpenClawRemoteConfig>);
     private perform;
-    ensureVersion(config: OpenClawSection, dryRun: boolean, _silent: boolean): Promise<EnsureVersionResult>;
+    ensureVersion(config: OpenClawSection, dryRun: boolean, _silent: boolean, _keepOpenClawState: boolean): Promise<EnsureVersionResult>;
     installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
     factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
     startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;

package/dist/openclaw/remote-provider.js

@@ -94,7 +94,7 @@ export class RemoteOpenClawProvider {
             clearTimeout(timeout);
         }
     }
-    async ensureVersion(config, dryRun, _silent) {
+    async ensureVersion(config, dryRun, _silent, _keepOpenClawState) {
         const result = await this.perform(config, "ensure_version", {
             install: config.install,
         }, dryRun);

package/dist/orchestrator.js

@@ -122,11 +122,14 @@ export async function runRecipe(recipe, recipeOrigin, options, logger) {
     const remoteMode = options.provider === "remote";
     const workspacePaths = new Map();
     logger.info(`Running recipe: ${recipe.name}`);
-    const versionResult = await provider.ensureVersion(recipe.openclaw, options.dryRun, options.silent);
+    const versionResult = await provider.ensureVersion(recipe.openclaw, options.dryRun, options.silent, options.keepOpenClawState);
     logger.info(`OpenClaw version ready: ${recipe.openclaw.version}`);
     if (versionResult.installedThisRun) {
         logger.info("OpenClaw was installed in this run; skipping factory reset");
     }
+    else if (options.keepOpenClawState) {
+        logger.info("Keeping existing OpenClaw state; skipping factory reset");
+    }
     else {
         const confirmed = await confirmFactoryReset(options);
         if (!confirmed) {

package/dist/recipe.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { tmpdir } from "node:os";
 import { spawn } from "node:child_process";
-import { readFile, mkdtemp, stat, writeFile, rm, mkdir } from "node:fs/promises";
+import { readFile, mkdtemp, stat, writeFile, rm, mkdir, readdir } from "node:fs/promises";
 import YAML from "js-yaml";
 import { recipeSchema } from "./schema.js";
 import { ClawChefError } from "./errors.js";
@@ -245,6 +245,128 @@ function parseUrlReference(input) {
         directUrl: parsed.toString(),
     };
 }
+function parseGitHubRepoReference(input) {
+    let parsed;
+    try {
+        parsed = new URL(input);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return undefined;
+    }
+    if (parsed.hostname.toLowerCase() !== "github.com") {
+        return undefined;
+    }
+    if (parsed.search || parsed.hash) {
+        return undefined;
+    }
+    const parts = parsed.pathname.split("/").filter((part) => part.length > 0);
+    if (parts.length !== 2) {
+        return undefined;
+    }
+    const owner = parts[0];
+    const repo = parts[1].endsWith(".git") ? parts[1].slice(0, -4) : parts[1];
+    if (!owner || !repo) {
+        return undefined;
+    }
+    return { owner, repo };
+}
+async function resolveRecipePathFromExtracted(extractDir, recipeInArchive, missingMessage) {
+    const directPath = path.join(extractDir, recipeInArchive);
+    try {
+        const directStat = await stat(directPath);
+        if (directStat.isFile()) {
+            return directPath;
+        }
+        throw new ClawChefError(`Recipe in archive is not a file: ${recipeInArchive}`);
+    }
+    catch (err) {
+        if (err instanceof ClawChefError) {
+            throw err;
+        }
+    }
+    const entries = await readdir(extractDir, { withFileTypes: true });
+    const matched = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const candidate = path.join(extractDir, entry.name, recipeInArchive);
+        try {
+            const s = await stat(candidate);
+            if (s.isFile()) {
+                matched.push(candidate);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    if (matched.length === 1) {
+        return matched[0];
+    }
+    if (matched.length > 1) {
+        throw new ClawChefError(`Multiple recipe files found in extracted archive for ${recipeInArchive}; provide explicit selector`);
+    }
+    throw new ClawChefError(missingMessage);
+}
+async function resolveGitHubRepoReference(recipeInput) {
+    const repoRef = parseGitHubRepoReference(recipeInput);
+    if (!repoRef) {
+        return undefined;
+    }
+    const repoApiUrl = `https://api.github.com/repos/${repoRef.owner}/${repoRef.repo}`;
+    const repoHeaders = {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "clawchef",
+    };
+    let repoResponse;
+    try {
+        repoResponse = await fetch(repoApiUrl, { headers: repoHeaders });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ClawChefError(`Failed to fetch GitHub repository metadata ${repoApiUrl}: ${message}`);
+    }
+    if (!repoResponse.ok) {
+        throw new ClawChefError(`Failed to fetch GitHub repository metadata ${repoApiUrl}: HTTP ${repoResponse.status}`);
+    }
+    const repoJson = (await repoResponse.json());
+    const defaultBranch = repoJson.default_branch?.trim();
+    if (!defaultBranch) {
+        throw new ClawChefError(`GitHub repository ${repoRef.owner}/${repoRef.repo} has no default branch`);
+    }
+    const tarballUrl = `https://api.github.com/repos/${repoRef.owner}/${repoRef.repo}/tarball/${encodeURIComponent(defaultBranch)}`;
+    let tarballResponse;
+    try {
+        tarballResponse = await fetch(tarballUrl, { headers: repoHeaders });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ClawChefError(`Failed to download GitHub repository tarball ${tarballUrl}: ${message}`);
+    }
+    if (!tarballResponse.ok) {
+        throw new ClawChefError(`Failed to download GitHub repository tarball ${tarballUrl}: HTTP ${tarballResponse.status}`);
+    }
+    const tempDir = await mkdtemp(path.join(tmpdir(), "clawchef-recipe-"));
+    const archivePath = path.join(tempDir, "repo.tar.gz");
+    await writeFile(archivePath, Buffer.from(await tarballResponse.arrayBuffer()));
+    const extractDir = path.join(tempDir, "extracted");
+    await mkdir(extractDir, { recursive: true });
+    await extractArchive(archivePath, extractDir);
+    const recipePath = await resolveRecipePathFromExtracted(extractDir, DEFAULT_RECIPE_FILE, `Recipe file not found in GitHub repository root: ${DEFAULT_RECIPE_FILE}`);
+    return {
+        recipePath,
+        origin: {
+            kind: "local",
+            recipePath,
+            recipeDir: path.dirname(recipePath),
+        },
+        cleanupPaths: [tempDir],
+    };
+}
 async function runCommand(command, args) {
     await new Promise((resolve, reject) => {
         const child = spawn(command, args, {
@@ -287,6 +409,10 @@ async function extractArchive(archivePath, extractDir) {
 }
 async function resolveRecipeReference(recipeInput) {
     if (isHttpUrl(recipeInput)) {
+        const githubResolved = await resolveGitHubRepoReference(recipeInput);
+        if (githubResolved) {
+            return githubResolved;
+        }
         const parsed = parseUrlReference(recipeInput);
         if (parsed.directUrl) {
             let response;
@@ -334,16 +460,7 @@ async function resolveRecipeReference(recipeInput) {
         await rm(extractDir, { recursive: true, force: true });
         await mkdir(extractDir, { recursive: true });
         await extractArchive(downloadedArchivePath, extractDir);
-        const recipePath = path.join(extractDir, recipeInArchive);
-        try {
-            const s = await stat(recipePath);
-            if (!s.isFile()) {
-                throw new ClawChefError(`Recipe in archive is not a file: ${recipeInArchive}`);
-            }
-        }
-        catch {
-            throw new ClawChefError(`Recipe file not found in archive: ${recipeInArchive}`);
-        }
+        const recipePath = await resolveRecipePathFromExtracted(extractDir, recipeInArchive, `Recipe file not found in archive: ${recipeInArchive}`);
         return {
             recipePath,
             origin: {
@@ -381,16 +498,7 @@ async function resolveRecipeReference(recipeInput) {
             const extractDir = path.join(tempDir, "extracted");
             await mkdir(extractDir, { recursive: true });
             await extractArchive(localPath, extractDir);
-            const recipePath = path.join(extractDir, DEFAULT_RECIPE_FILE);
-            try {
-                const s = await stat(recipePath);
-                if (!s.isFile()) {
-                    throw new ClawChefError(`Recipe in archive is not a file: ${DEFAULT_RECIPE_FILE}`);
-                }
-            }
-            catch {
-                throw new ClawChefError(`Recipe file not found in archive: ${DEFAULT_RECIPE_FILE}`);
-            }
+            const recipePath = await resolveRecipePathFromExtracted(extractDir, DEFAULT_RECIPE_FILE, `Recipe file not found in archive: ${DEFAULT_RECIPE_FILE}`);
             return {
                 recipePath,
                 origin: {
@@ -445,16 +553,7 @@ async function resolveRecipeReference(recipeInput) {
         const extractDir = path.join(tempDir, "extracted");
         await mkdir(extractDir, { recursive: true });
         await extractArchive(basePath, extractDir);
-        const recipePath = path.join(extractDir, selector);
-        try {
-            const s = await stat(recipePath);
-            if (!s.isFile()) {
-                throw new ClawChefError(`Recipe in archive is not a file: ${selector}`);
-            }
-        }
-        catch {
-            throw new ClawChefError(`Recipe file not found in archive: ${selector}`);
-        }
+        const recipePath = await resolveRecipePathFromExtracted(extractDir, selector, `Recipe file not found in archive: ${selector}`);
         return {
             recipePath,
             origin: {

package/dist/scaffold.js

@@ -76,7 +76,7 @@ openclaw:
 
 workspaces:
   - name: "\${workspace_name}"
-    assets: "./${projectName}-assets"
+    assets: "./assets"
 
 agents:
   - workspace: "\${workspace_name}"
@@ -134,11 +134,17 @@ console.log("[scheduling] " + message);
 function makeRecipeSmokeTest() {
     return `import test from "node:test";
 import assert from "node:assert/strict";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { access } from "node:fs/promises";
 
+const testDir = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(testDir, "..");
+
 test("recipe scaffold files exist", async () => {
-  await access("src/recipe.yaml");
-  await access("package.json");
+  await access(path.join(projectRoot, "recipe.yaml"));
+  await access(path.join(projectRoot, "assets", "AGENTS.md"));
+  await access(path.join(projectRoot, "package.json"));
   assert.ok(true);
 });
 `;
@@ -149,16 +155,14 @@ export async function scaffoldProject(targetDirArg, options = {}) {
     const defaultName = path.basename(targetDir);
     const rawProjectName = options.projectName?.trim() || defaultName;
     const projectName = normalizeProjectName(rawProjectName);
-    const srcDir = path.join(targetDir, "src");
-    const assetsDir = path.join(srcDir, `${projectName}-assets`);
+    const assetsDir = path.join(targetDir, "assets");
     const assetsScriptsDir = path.join(assetsDir, "scripts");
     const testDir = path.join(targetDir, "test");
-    await mkdir(srcDir, { recursive: true });
     await mkdir(assetsDir, { recursive: true });
     await mkdir(assetsScriptsDir, { recursive: true });
     await mkdir(testDir, { recursive: true });
     await writeFile(path.join(targetDir, "package.json"), makePackageJson(projectName), "utf8");
-    await writeFile(path.join(srcDir, "recipe.yaml"), makeRecipeYaml(projectName), "utf8");
+    await writeFile(path.join(targetDir, "recipe.yaml"), makeRecipeYaml(projectName), "utf8");
     await writeFile(path.join(assetsDir, "AGENTS.md"), makeAgentsDoc(projectName), "utf8");
     await writeFile(path.join(assetsDir, "IDENTITY.md"), makeIdentityDoc(projectName), "utf8");
     await writeFile(path.join(assetsDir, "SOUL.md"), makeSoulDoc(), "utf8");

package/dist/types.d.ts

@@ -135,6 +135,7 @@ export interface RunOptions {
     allowMissing: boolean;
     verbose: boolean;
     silent: boolean;
+    keepOpenClawState: boolean;
     provider: OpenClawProvider;
     remote: Partial<OpenClawRemoteConfig>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawchef",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Recipe-driven OpenClaw environment orchestrator",
   "homepage": "https://renorzr.github.io/clawchef",
   "repository": {

package/src/api.ts

@@ -30,6 +30,7 @@ function normalizeCookOptions(options: CookOptions): RunOptions {
     allowMissing: Boolean(options.allowMissing),
     verbose: Boolean(options.verbose),
     silent: options.silent ?? true,
+    keepOpenClawState: false,
     provider: options.provider ?? "command",
     remote: options.remote ?? {},
   };

package/src/cli.ts

@@ -87,6 +87,7 @@ export function buildCli(): Command {
     .option("--allow-missing", "Allow unresolved template variables", false)
     .option("--verbose", "Verbose logging", false)
     .option("-s, --silent", "Skip reset confirmation prompt", false)
+    .option("--keep-openclaw-state", "Preserve existing OpenClaw state (skip factory reset)", false)
     .option("--provider <provider>", "Execution provider: command | remote | mock")
     .option("--plugin <npm-spec>", "Preinstall plugin package (repeatable)", (v, p: string[]) => p.concat([v]), [])
     .option("--remote-base-url <url>", "Remote OpenClaw API base URL")
@@ -104,6 +105,7 @@ export function buildCli(): Command {
         allowMissing: Boolean(opts.allowMissing),
         verbose: Boolean(opts.verbose),
         silent: Boolean(opts.silent),
+        keepOpenClawState: Boolean(opts.keepOpenclawState),
         provider,
         remote: {
           base_url: opts.remoteBaseUrl ?? readEnv("CLAWCHEF_REMOTE_BASE_URL"),

package/src/openclaw/command-provider.ts

@@ -273,7 +273,12 @@ function bootstrapRuntimeEnv(bootstrap: OpenClawBootstrap | undefined): Record<s
 export class CommandOpenClawProvider implements OpenClawProvider {
   private readonly stagedMessages = new Map<string, StagedMessage[]>();
 
-  async ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean): Promise<EnsureVersionResult> {
+  async ensureVersion(
+    config: OpenClawSection,
+    dryRun: boolean,
+    silent: boolean,
+    keepOpenClawState: boolean,
+  ): Promise<EnsureVersionResult> {
     const bin = config.bin ?? "openclaw";
     const installPolicy = config.install ?? "auto";
     const useCmd = commandFor(config, "use_version", { bin, version: config.version });
@@ -338,6 +343,10 @@ export class CommandOpenClawProvider implements OpenClawProvider {
       );
     }
 
+    if (keepOpenClawState) {
+      return { installedThisRun: false };
+    }
+
     const choice = await chooseVersionMismatchAction(currentVersion, config.version, silent);
 
     if (choice === "ignore") {

package/src/openclaw/mock-provider.ts

@@ -21,7 +21,12 @@ export class MockOpenClawProvider implements OpenClawProvider {
     messages: new Map(),
   };
 
-  async ensureVersion(config: OpenClawSection, _dryRun: boolean, _silent: boolean): Promise<EnsureVersionResult> {
+  async ensureVersion(
+    config: OpenClawSection,
+    _dryRun: boolean,
+    _silent: boolean,
+    _keepOpenClawState: boolean,
+  ): Promise<EnsureVersionResult> {
     const policy = config.install ?? "auto";
     const installed = this.state.installedVersions.has(config.version);
     let installedThisRun = false;

package/src/openclaw/provider.ts

@@ -7,7 +7,12 @@ export interface EnsureVersionResult {
 }
 
 export interface OpenClawProvider {
-  ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean): Promise<EnsureVersionResult>;
+  ensureVersion(
+    config: OpenClawSection,
+    dryRun: boolean,
+    silent: boolean,
+    keepOpenClawState: boolean,
+  ): Promise<EnsureVersionResult>;
   installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
   factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
   startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;

package/src/openclaw/remote-provider.ts

@@ -141,7 +141,12 @@ export class RemoteOpenClawProvider implements OpenClawProvider {
     }
   }
 
-  async ensureVersion(config: OpenClawSection, dryRun: boolean, _silent: boolean): Promise<EnsureVersionResult> {
+  async ensureVersion(
+    config: OpenClawSection,
+    dryRun: boolean,
+    _silent: boolean,
+    _keepOpenClawState: boolean,
+  ): Promise<EnsureVersionResult> {
     const result = await this.perform(
       config,
       "ensure_version",

package/src/orchestrator.ts

@@ -148,11 +148,18 @@ export async function runRecipe(
   const workspacePaths = new Map<string, string>();
 
   logger.info(`Running recipe: ${recipe.name}`);
-  const versionResult = await provider.ensureVersion(recipe.openclaw, options.dryRun, options.silent);
+  const versionResult = await provider.ensureVersion(
+    recipe.openclaw,
+    options.dryRun,
+    options.silent,
+    options.keepOpenClawState,
+  );
   logger.info(`OpenClaw version ready: ${recipe.openclaw.version}`);
 
   if (versionResult.installedThisRun) {
     logger.info("OpenClaw was installed in this run; skipping factory reset");
+  } else if (options.keepOpenClawState) {
+    logger.info("Keeping existing OpenClaw state; skipping factory reset");
   } else {
     const confirmed = await confirmFactoryReset(options);
     if (!confirmed) {

package/src/recipe.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { tmpdir } from "node:os";
 import { spawn } from "node:child_process";
-import { readFile, mkdtemp, stat, writeFile, rm, mkdir } from "node:fs/promises";
+import { readFile, mkdtemp, stat, writeFile, rm, mkdir, readdir } from "node:fs/promises";
 import YAML from "js-yaml";
 import { recipeSchema } from "./schema.js";
 import { ClawChefError } from "./errors.js";
@@ -266,6 +266,11 @@ interface ResolvedRecipeReference {
   cleanupPaths: string[];
 }
 
+interface GitHubRepoRef {
+  owner: string;
+  repo: string;
+}
+
 function isHttpUrl(value: string): boolean {
   try {
     const url = new URL(value);
@@ -323,6 +328,149 @@ function parseUrlReference(input: string): { archiveUrl: string; inner?: string;
   };
 }
 
+function parseGitHubRepoReference(input: string): GitHubRepoRef | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(input);
+  } catch {
+    return undefined;
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return undefined;
+  }
+  if (parsed.hostname.toLowerCase() !== "github.com") {
+    return undefined;
+  }
+  if (parsed.search || parsed.hash) {
+    return undefined;
+  }
+
+  const parts = parsed.pathname.split("/").filter((part) => part.length > 0);
+  if (parts.length !== 2) {
+    return undefined;
+  }
+
+  const owner = parts[0];
+  const repo = parts[1].endsWith(".git") ? parts[1].slice(0, -4) : parts[1];
+  if (!owner || !repo) {
+    return undefined;
+  }
+
+  return { owner, repo };
+}
+
+async function resolveRecipePathFromExtracted(
+  extractDir: string,
+  recipeInArchive: string,
+  missingMessage: string,
+): Promise<string> {
+  const directPath = path.join(extractDir, recipeInArchive);
+  try {
+    const directStat = await stat(directPath);
+    if (directStat.isFile()) {
+      return directPath;
+    }
+    throw new ClawChefError(`Recipe in archive is not a file: ${recipeInArchive}`);
+  } catch (err) {
+    if (err instanceof ClawChefError) {
+      throw err;
+    }
+  }
+
+  const entries = await readdir(extractDir, { withFileTypes: true });
+  const matched: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const candidate = path.join(extractDir, entry.name, recipeInArchive);
+    try {
+      const s = await stat(candidate);
+      if (s.isFile()) {
+        matched.push(candidate);
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  if (matched.length === 1) {
+    return matched[0];
+  }
+  if (matched.length > 1) {
+    throw new ClawChefError(`Multiple recipe files found in extracted archive for ${recipeInArchive}; provide explicit selector`);
+  }
+
+  throw new ClawChefError(missingMessage);
+}
+
+async function resolveGitHubRepoReference(recipeInput: string): Promise<ResolvedRecipeReference | undefined> {
+  const repoRef = parseGitHubRepoReference(recipeInput);
+  if (!repoRef) {
+    return undefined;
+  }
+
+  const repoApiUrl = `https://api.github.com/repos/${repoRef.owner}/${repoRef.repo}`;
+  const repoHeaders = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "clawchef",
+  };
+
+  let repoResponse: Response;
+  try {
+    repoResponse = await fetch(repoApiUrl, { headers: repoHeaders });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ClawChefError(`Failed to fetch GitHub repository metadata ${repoApiUrl}: ${message}`);
+  }
+  if (!repoResponse.ok) {
+    throw new ClawChefError(`Failed to fetch GitHub repository metadata ${repoApiUrl}: HTTP ${repoResponse.status}`);
+  }
+
+  const repoJson = (await repoResponse.json()) as { default_branch?: string };
+  const defaultBranch = repoJson.default_branch?.trim();
+  if (!defaultBranch) {
+    throw new ClawChefError(`GitHub repository ${repoRef.owner}/${repoRef.repo} has no default branch`);
+  }
+
+  const tarballUrl = `https://api.github.com/repos/${repoRef.owner}/${repoRef.repo}/tarball/${encodeURIComponent(defaultBranch)}`;
+  let tarballResponse: Response;
+  try {
+    tarballResponse = await fetch(tarballUrl, { headers: repoHeaders });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ClawChefError(`Failed to download GitHub repository tarball ${tarballUrl}: ${message}`);
+  }
+  if (!tarballResponse.ok) {
+    throw new ClawChefError(`Failed to download GitHub repository tarball ${tarballUrl}: HTTP ${tarballResponse.status}`);
+  }
+
+  const tempDir = await mkdtemp(path.join(tmpdir(), "clawchef-recipe-"));
+  const archivePath = path.join(tempDir, "repo.tar.gz");
+  await writeFile(archivePath, Buffer.from(await tarballResponse.arrayBuffer()));
+
+  const extractDir = path.join(tempDir, "extracted");
+  await mkdir(extractDir, { recursive: true });
+  await extractArchive(archivePath, extractDir);
+
+  const recipePath = await resolveRecipePathFromExtracted(
+    extractDir,
+    DEFAULT_RECIPE_FILE,
+    `Recipe file not found in GitHub repository root: ${DEFAULT_RECIPE_FILE}`,
+  );
+
+  return {
+    recipePath,
+    origin: {
+      kind: "local",
+      recipePath,
+      recipeDir: path.dirname(recipePath),
+    },
+    cleanupPaths: [tempDir],
+  };
+}
+
 async function runCommand(command: string, args: string[]): Promise<void> {
   await new Promise<void>((resolve, reject) => {
     const child = spawn(command, args, {
@@ -370,6 +518,11 @@ async function extractArchive(archivePath: string, extractDir: string): Promise<
 
 async function resolveRecipeReference(recipeInput: string): Promise<ResolvedRecipeReference> {
   if (isHttpUrl(recipeInput)) {
+    const githubResolved = await resolveGitHubRepoReference(recipeInput);
+    if (githubResolved) {
+      return githubResolved;
+    }
+
     const parsed = parseUrlReference(recipeInput);
     if (parsed.directUrl) {
       let response: Response;
@@ -421,15 +574,11 @@ async function resolveRecipeReference(recipeInput: string): Promise<ResolvedReci
     await mkdir(extractDir, { recursive: true });
     await extractArchive(downloadedArchivePath, extractDir);
 
-    const recipePath = path.join(extractDir, recipeInArchive);
-    try {
-      const s = await stat(recipePath);
-      if (!s.isFile()) {
-        throw new ClawChefError(`Recipe in archive is not a file: ${recipeInArchive}`);
-      }
-    } catch {
-      throw new ClawChefError(`Recipe file not found in archive: ${recipeInArchive}`);
-    }
+    const recipePath = await resolveRecipePathFromExtracted(
+      extractDir,
+      recipeInArchive,
+      `Recipe file not found in archive: ${recipeInArchive}`,
+    );
 
     return {
       recipePath,
@@ -470,15 +619,11 @@ async function resolveRecipeReference(recipeInput: string): Promise<ResolvedReci
       const extractDir = path.join(tempDir, "extracted");
       await mkdir(extractDir, { recursive: true });
       await extractArchive(localPath, extractDir);
-      const recipePath = path.join(extractDir, DEFAULT_RECIPE_FILE);
-      try {
-        const s = await stat(recipePath);
-        if (!s.isFile()) {
-          throw new ClawChefError(`Recipe in archive is not a file: ${DEFAULT_RECIPE_FILE}`);
-        }
-      } catch {
-        throw new ClawChefError(`Recipe file not found in archive: ${DEFAULT_RECIPE_FILE}`);
-      }
+      const recipePath = await resolveRecipePathFromExtracted(
+        extractDir,
+        DEFAULT_RECIPE_FILE,
+        `Recipe file not found in archive: ${DEFAULT_RECIPE_FILE}`,
+      );
       return {
         recipePath,
         origin: {
@@ -538,15 +683,11 @@ async function resolveRecipeReference(recipeInput: string): Promise<ResolvedReci
     const extractDir = path.join(tempDir, "extracted");
     await mkdir(extractDir, { recursive: true });
     await extractArchive(basePath, extractDir);
-    const recipePath = path.join(extractDir, selector);
-    try {
-      const s = await stat(recipePath);
-      if (!s.isFile()) {
-        throw new ClawChefError(`Recipe in archive is not a file: ${selector}`);
-      }
-    } catch {
-      throw new ClawChefError(`Recipe file not found in archive: ${selector}`);
-    }
+    const recipePath = await resolveRecipePathFromExtracted(
+      extractDir,
+      selector,
+      `Recipe file not found in archive: ${selector}`,
+    );
     return {
       recipePath,
       origin: {

package/src/scaffold.ts

@@ -89,7 +89,7 @@ openclaw:
 
 workspaces:
   - name: "\${workspace_name}"
-    assets: "./${projectName}-assets"
+    assets: "./assets"
 
 agents:
   - workspace: "\${workspace_name}"
@@ -153,11 +153,17 @@ console.log("[scheduling] " + message);
 function makeRecipeSmokeTest(): string {
   return `import test from "node:test";
 import assert from "node:assert/strict";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { access } from "node:fs/promises";
 
+const testDir = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(testDir, "..");
+
 test("recipe scaffold files exist", async () => {
-  await access("src/recipe.yaml");
-  await access("package.json");
+  await access(path.join(projectRoot, "recipe.yaml"));
+  await access(path.join(projectRoot, "assets", "AGENTS.md"));
+  await access(path.join(projectRoot, "package.json"));
   assert.ok(true);
 });
 `;
@@ -171,18 +177,16 @@ export async function scaffoldProject(targetDirArg?: string, options: ScaffoldOp
   const rawProjectName = options.projectName?.trim() || defaultName;
   const projectName = normalizeProjectName(rawProjectName);
 
-  const srcDir = path.join(targetDir, "src");
-  const assetsDir = path.join(srcDir, `${projectName}-assets`);
+  const assetsDir = path.join(targetDir, "assets");
   const assetsScriptsDir = path.join(assetsDir, "scripts");
   const testDir = path.join(targetDir, "test");
 
-  await mkdir(srcDir, { recursive: true });
   await mkdir(assetsDir, { recursive: true });
   await mkdir(assetsScriptsDir, { recursive: true });
   await mkdir(testDir, { recursive: true });
 
   await writeFile(path.join(targetDir, "package.json"), makePackageJson(projectName), "utf8");
-  await writeFile(path.join(srcDir, "recipe.yaml"), makeRecipeYaml(projectName), "utf8");
+  await writeFile(path.join(targetDir, "recipe.yaml"), makeRecipeYaml(projectName), "utf8");
   await writeFile(path.join(assetsDir, "AGENTS.md"), makeAgentsDoc(projectName), "utf8");
   await writeFile(path.join(assetsDir, "IDENTITY.md"), makeIdentityDoc(projectName), "utf8");
   await writeFile(path.join(assetsDir, "SOUL.md"), makeSoulDoc(), "utf8");

package/src/types.ts

@@ -149,6 +149,7 @@ export interface RunOptions {
   allowMissing: boolean;
   verbose: boolean;
   silent: boolean;
+  keepOpenClawState: boolean;
   provider: OpenClawProvider;
   remote: Partial<OpenClawRemoteConfig>;
 }