@jiggai/recipes 0.2.17 → 0.2.18

package/README.md

@@ -56,8 +56,8 @@ openclaw recipes dispatch \
 
 ## Commands (high level)
 - `openclaw recipes list|show|status`
-- `openclaw recipes scaffold` (agent → `workspace-<agentId>`)
-- `openclaw recipes scaffold-team` (team → `workspace-<teamId>` + `roles/<role>/`)
+- `openclaw recipes scaffold` (agent → `workspace-<agentId>` + writes workspace recipe `~/.openclaw/workspace/recipes/<agentId>.md` by default)
+- `openclaw recipes scaffold-team` (team → `workspace-<teamId>` + `roles/<role>/` + writes workspace recipe `~/.openclaw/workspace/recipes/<teamId>.md` by default)
 - `openclaw recipes install <idOrSlug> [--yes] [--global|--agent-id <id>|--team-id <id>]` (skills: global or scoped)
 - `openclaw recipes bind|unbind|bindings` (multi-agent routing)
 - `openclaw recipes dispatch ...` (request → inbox + ticket + assignment)

package/docs/COMMANDS.md

@@ -41,9 +41,15 @@ openclaw recipes scaffold project-manager --agent-id pm --name "Project Manager"
 Options:
 - `--agent-id <id>` (required)
 - `--name <name>`
+- `--recipe-id <recipeId>` (workspace recipe id to write; default: `<agentId>`)
+- `--auto-increment` (if the workspace recipe id is taken, pick `<agentId>-2/-3/...`)
+- `--overwrite-recipe` (overwrite the generated workspace recipe file if it already exists)
 - `--overwrite` (overwrite recipe-managed files)
 - `--apply-config` (write/update `agents.list[]` in OpenClaw config)
 
+Also writes a workspace recipe file:
+- `~/.openclaw/workspace/recipes/<recipeId>.md`
+
 ## `scaffold-team <recipeId>`
 
 ### Cron installation config
@@ -64,9 +70,15 @@ openclaw recipes scaffold-team development-team \
 Options:
 - `--team-id <teamId>` (required)
   - **Must end with `-team`** (enforced)
+- `--recipe-id <recipeId>` (workspace recipe id to write; default: `<teamId>`)
+- `--auto-increment` (if the workspace recipe id is taken, pick `<teamId>-2/-3/...`)
+- `--overwrite-recipe` (overwrite the generated workspace recipe file if it already exists)
 - `--overwrite`
 - `--apply-config`
 
+Also writes a workspace recipe file:
+- `~/.openclaw/workspace/recipes/<recipeId>.md`
+
 Creates a shared team workspace root:
 
 - `~/.openclaw/workspace-<teamId>/...`

package/index.ts

@@ -2092,7 +2092,10 @@ const recipesPlugin = {
           .argument("<recipeId>", "Recipe id")
           .requiredOption("--agent-id <id>", "Agent id")
           .option("--name <name>", "Agent display name")
+          .option("--recipe-id <recipeId>", "Workspace recipe id to write (default: <agentId>)")
           .option("--overwrite", "Overwrite existing recipe-managed files")
+          .option("--overwrite-recipe", "Overwrite the generated workspace recipe file (workspace/recipes/<agentId>.md) if it already exists")
+          .option("--auto-increment", "If the workspace recipe id is taken, pick the next available <agentId>-2/-3/...")
           .option("--apply-config", "Write the agent into openclaw config (agents.list)")
           .action(async (recipeId: string, options: any) => {
             const loaded = await loadRecipeById(api, recipeId);
@@ -2113,19 +2116,86 @@ const recipesPlugin = {
               return;
             }
 
+            const agentId = String(options.agentId);
             const baseWorkspace = api.config.agents?.defaults?.workspace ?? "~/.openclaw/workspace";
             // Put standalone agent workspaces alongside the default workspace (same parent dir).
-            const resolvedWorkspaceRoot = path.resolve(baseWorkspace, "..", `workspace-${options.agentId}`);
+            const resolvedWorkspaceRoot = path.resolve(baseWorkspace, "..", `workspace-${agentId}`);
+
+            // Also create a workspace recipe file for this installed agent.
+            // This establishes a stable, editable recipe id that matches the agent id (no custom- prefix).
+            const recipesDir = path.join(workspaceRoot, "recipes");
+            await ensureDir(recipesDir);
+
+            const overwriteRecipe = !!options.overwriteRecipe;
+            const autoIncrement = !!options.autoIncrement;
+
+            function suggestedRecipeIds(baseId: string) {
+              return [`${baseId}-2`, `${baseId}-3`, `${baseId}-4`];
+            }
+
+            async function recipeIdTaken(id: string) {
+              const filePath = path.join(recipesDir, `${id}.md`);
+              if (await fileExists(filePath)) return true;
+              try {
+                await loadRecipeById(api, id);
+                return true;
+              } catch {
+                return false;
+              }
+            }
+
+            async function pickRecipeId(baseId: string) {
+              if (!(await recipeIdTaken(baseId))) return baseId;
+              if (overwriteRecipe) {
+                const basePath = path.join(recipesDir, `${baseId}.md`);
+                if (!(await fileExists(basePath))) {
+                  throw new Error(
+                    `Recipe id is already taken by a non-workspace recipe: ${baseId}. Choose a different id (e.g. ${baseId}-2) or pass --auto-increment.`,
+                  );
+                }
+                return baseId;
+              }
+
+              if (autoIncrement) {
+                let n = 2;
+                while (n < 1000) {
+                  const candidate = `${baseId}-${n}`;
+                  if (!(await recipeIdTaken(candidate))) return candidate;
+                  n += 1;
+                }
+                throw new Error(`No available recipe id found for ${baseId} (tried up to -999)`);
+              }
+
+              const suggestions = suggestedRecipeIds(baseId);
+              const msg = [
+                `Recipe id already exists: ${baseId}`,
+                `Refusing to overwrite workspace recipe: recipes/${baseId}.md`,
+                `Pick a different recipe id and re-run with --recipe-id. Suggestions: ${suggestions.join(", ")}`,
+                ...suggestions.map((s) => `  openclaw recipes scaffold ${recipeId} --agent-id ${agentId} --recipe-id ${s}`),
+                `Or re-run with --auto-increment to pick ${baseId}-2/-3/... automatically, or pass --overwrite-recipe to overwrite the existing workspace recipe file.`,
+              ].join("\n");
+              throw new Error(msg);
+            }
+
+            const explicitRecipeId = typeof options.recipeId === "string" ? String(options.recipeId).trim() : "";
+            const baseRecipeId = explicitRecipeId || agentId;
+            const workspaceRecipeId = await pickRecipeId(baseRecipeId);
+
+            const recipeFilePath = path.join(recipesDir, `${workspaceRecipeId}.md`);
+            const parsed = parseFrontmatter(loaded.md);
+            const fm = { ...parsed.frontmatter, id: workspaceRecipeId, name: parsed.frontmatter.name ?? recipe.name ?? workspaceRecipeId };
+            const nextMd = `---\n${YAML.stringify(fm)}---\n${parsed.body}`;
+            await writeFileSafely(recipeFilePath, nextMd, overwriteRecipe ? "overwrite" : "createOnly");
 
             const result = await scaffoldAgentFromRecipe(api, recipe, {
-              agentId: options.agentId,
+              agentId,
               agentName: options.name,
               update: !!options.overwrite,
               filesRootDir: resolvedWorkspaceRoot,
               workspaceRootDir: resolvedWorkspaceRoot,
               vars: {
-                agentId: options.agentId,
-                agentName: options.name ?? recipe.name ?? options.agentId,
+                agentId,
+                agentName: options.name ?? recipe.name ?? agentId,
               },
             });
 
@@ -2147,8 +2217,11 @@ const recipesPlugin = {
           .command("scaffold-team")
           .description("Scaffold a team (shared workspace + multiple agents) from a team recipe")
           .argument("<recipeId>", "Recipe id")
-          .requiredOption("-t, --team-id <teamId>", "Team id (must end with -team)")
+          .requiredOption("-t, --team-id <teamId>", "Team id")
+          .option("--recipe-id <recipeId>", "Custom workspace recipe id to write (default: <teamId>)")
           .option("--overwrite", "Overwrite existing recipe-managed files")
+          .option("--overwrite-recipe", "Overwrite the generated workspace recipe file (workspace/recipes/<teamId>.md) if it already exists")
+          .option("--auto-increment", "If the workspace recipe id is taken, pick the next available <teamId>-2/-3/...")
           .option("--apply-config", "Write all team agents into openclaw config (agents.list)")
           .action(async (recipeId: string, options: any) => {
             const loaded = await loadRecipeById(api, recipeId);
@@ -2157,9 +2230,6 @@ const recipesPlugin = {
               throw new Error(`Recipe is not a team recipe: kind=${recipe.kind}`);
             }
             const teamId = String(options.teamId);
-            if (!teamId.endsWith("-team")) {
-              throw new Error("teamId must end with -team");
-            }
 
             const cfg = getCfg(api);
             const baseWorkspace = api.config.agents?.defaults?.workspace;
@@ -2177,6 +2247,57 @@ const recipesPlugin = {
             const teamDir = path.resolve(baseWorkspace, "..", `workspace-${teamId}`);
             await ensureDir(teamDir);
 
+
+            // Also create a workspace recipe file for this installed team.
+            // This establishes a stable, editable recipe id that matches the team id (no custom- prefix).
+            const recipesDir = path.join(baseWorkspace, "recipes");
+            await ensureDir(recipesDir);
+
+            const overwriteRecipe = !!options.overwriteRecipe;
+            const autoIncrement = !!options.autoIncrement;
+
+            function suggestedRecipeIds(baseId: string) {
+              const today = new Date().toISOString().slice(0, 10);
+              return [`${baseId}-v2`, `${baseId}-${today}`, `${baseId}-alt`];
+            }
+
+            async function pickRecipeId(baseId: string) {
+              const basePath = path.join(recipesDir, `${baseId}.md`);
+              if (!(await fileExists(basePath))) return baseId;
+              if (overwriteRecipe) return baseId;
+              if (autoIncrement) {
+                let n = 2;
+                while (n < 1000) {
+                  const candidate = `${baseId}-${n}`;
+                  const candidatePath = path.join(recipesDir, `${candidate}.md`);
+                  if (!(await fileExists(candidatePath))) return candidate;
+                  n += 1;
+                }
+                throw new Error(`No available recipe id found for ${baseId} (tried up to -999)`);
+              }
+
+              const suggestions = suggestedRecipeIds(baseId);
+              const msg = [
+                `Workspace recipe already exists: recipes/${baseId}.md`,
+                `Choose a different recipe id (recommended) and re-run with --recipe-id, for example:`,
+                ...suggestions.map((s) => `  openclaw recipes scaffold-team ${recipeId} -t ${teamId} --recipe-id ${s}`),
+                `Or re-run with --auto-increment to pick ${baseId}-2/-3/... automatically, or --overwrite-recipe to overwrite the existing file.`,
+              ].join("\n");
+              throw new Error(msg);
+            }
+
+            const explicitRecipeId = typeof options.recipeId === "string" ? String(options.recipeId).trim() : "";
+            const baseRecipeId = explicitRecipeId || teamId;
+            const workspaceRecipeId = await pickRecipeId(baseRecipeId);
+
+            // Write the recipe file, copying the source recipe markdown but forcing frontmatter.id to the chosen id.
+            // Default: createOnly; overwrite only when --overwrite-recipe is set.
+            const recipeFilePath = path.join(recipesDir, `${workspaceRecipeId}.md`);
+            const parsed = parseFrontmatter(loaded.md);
+            const fm = { ...parsed.frontmatter, id: workspaceRecipeId, name: parsed.frontmatter.name ?? recipe.name ?? workspaceRecipeId };
+            const nextMd = `---\n${YAML.stringify(fm)}---\n${parsed.body}`;
+            await writeFileSafely(recipeFilePath, nextMd, overwriteRecipe ? "overwrite" : "createOnly");
+
             const rolesDir = path.join(teamDir, "roles");
             await ensureDir(rolesDir);
             const notesDir = path.join(teamDir, "notes");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiggai/recipes",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "ClawRecipes plugin for OpenClaw (markdown recipes -> scaffold agents/teams)",
   "main": "index.ts",
   "type": "commonjs",
@@ -24,6 +24,8 @@
   "scripts": {
     "test": "vitest run",
     "test:smoke": "node scripts/scaffold-smoke.mjs",
+    "test:provenance-smoke": "node scripts/scaffold-team-provenance-smoke.mjs",
+    "test:agent-recipefile-smoke": "node scripts/scaffold-agent-recipefile-smoke.mjs",
     "smoke": "node scripts/scaffold-smoke.mjs",
     "scaffold:smoke": "node scripts/scaffold-smoke.mjs"
   },