@jiggai/recipes 0.2.17 → 0.2.20

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/BUNDLED_RECIPES.md

@@ -193,6 +193,87 @@ Default tool policy:
 - allows `group:runtime`
 - does not deny `exec`
 
+---
+
+# Vertical packs (bundled team recipes)
+
+## 11) `business-team` (team)
+**Use when:** you want a general-purpose business execution team.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team business-team --team-id business-team-team --apply-config
+```
+
+Roles:
+- lead, ops, sales, marketing, finance, analyst
+
+## 12) `law-firm-team` (team)
+**Use when:** you want a legal practice workflow: intake → research → drafting → compliance.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team law-firm-team --team-id law-firm-team-team --apply-config
+```
+
+Roles:
+- lead, intake, researcher, drafter, compliance, ops
+
+## 13) `clinic-team` (team)
+**Use when:** you want a clinic ops workflow: intake/scheduling/billing/compliance/patient education.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team clinic-team --team-id clinic-team-team --apply-config
+```
+
+Roles:
+- lead, intake, scheduler, billing, compliance, educator
+
+## 14) `construction-team` (team)
+**Use when:** you want a construction delivery workflow: PM/estimation/scheduling/safety/procurement.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team construction-team --team-id construction-team-team --apply-config
+```
+
+Roles:
+- lead, pm, estimator, scheduler, safety, procurement
+
+## 15) `financial-planner-team` (team)
+**Use when:** you want a financial planning practice workflow.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team financial-planner-team --team-id financial-planner-team-team --apply-config
+```
+
+Roles:
+- lead, advisor, analyst, tax, insurance, ops
+
+## 16) `stock-trader-team` (team)
+**Use when:** you want a trading workflow: research/signals/risk/journaling.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team stock-trader-team --team-id stock-trader-team-team --apply-config
+```
+
+Roles:
+- lead, researcher, signals, risk, journal, ops
+
+## 17) `crypto-trader-team` (team)
+**Use when:** you want a crypto trading workflow with onchain research.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team crypto-trader-team --team-id crypto-trader-team-team --apply-config
+```
+
+Roles:
+- lead, onchain, news, risk, ops, journal
+
 ## Copying and modifying bundled recipes
 A good workflow is:
 1) Inspect:

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");
@@ -2222,14 +2343,22 @@ const recipesPlugin = {
 
             const planPath = path.join(notesDir, "plan.md");
             const statusPath = path.join(notesDir, "status.md");
+            const goalsIndexPath = path.join(notesDir, "GOALS.md");
+            const goalsDir = path.join(notesDir, "goals");
+            const goalsReadmePath = path.join(goalsDir, "README.md");
             const ticketsPath = path.join(teamDir, "TICKETS.md");
 
             const planMd = `# Plan — ${teamId}\n\n- (empty)\n`;
             const statusMd = `# Status — ${teamId}\n\n- (empty)\n`;
+            const goalsIndexMd = `# Goals — ${teamId}\n\nThis folder is the canonical home for goals.\n\n## How to use\n- Create one markdown file per goal under: notes/goals/\n- Add a link here for discoverability\n\n## Goals\n- (empty)\n`;
+            const goalsReadmeMd = `# Goals folder — ${teamId}\n\nCreate one markdown file per goal in this directory.\n\nRecommended file naming:\n- short, kebab-case, no leading numbers (e.g. \`reduce-support-backlog.md\`)\n\nLink goals from:\n- notes/GOALS.md\n`;
             const ticketsMd = `# Tickets — ${teamId}\n\n## Naming\n- Backlog tickets live in work/backlog/\n- In-progress tickets live in work/in-progress/\n- Testing tickets live in work/testing/\n- Done tickets live in work/done/\n- Filename ordering is the queue: 0001-..., 0002-...\n\n## Stages\n- backlog → in-progress → testing → done\n\n## QA handoff\n- When work is ready for QA: move the ticket to \`work/testing/\` and assign to test.\n\n## Required fields\nEach ticket should include:\n- Title\n- Context\n- Requirements\n- Acceptance criteria\n- Owner (dev/devops/lead/test)\n- Status (queued/in-progress/testing/done)\n\n## Example\n\n\`\`\`md\n# 0001-example-ticket\n\nOwner: dev\nStatus: queued\n\n## Context\n...\n\n## Requirements\n- ...\n\n## Acceptance criteria\n- ...\n\`\`\`\n`;
 
+            await ensureDir(goalsDir);
             await writeFileSafely(planPath, planMd, overwrite ? "overwrite" : "createOnly");
             await writeFileSafely(statusPath, statusMd, overwrite ? "overwrite" : "createOnly");
+            await writeFileSafely(goalsIndexPath, goalsIndexMd, overwrite ? "overwrite" : "createOnly");
+            await writeFileSafely(goalsReadmePath, goalsReadmeMd, overwrite ? "overwrite" : "createOnly");
             await writeFileSafely(ticketsPath, ticketsMd, overwrite ? "overwrite" : "createOnly");
 
             const agents = recipe.agents ?? [];

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "recipes",
   "name": "Recipes",
   "description": "Markdown recipes that scaffold agents and teams (workspace-local).",
-  "version": "0.2.17",
+  "version": "0.2.20",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiggai/recipes",
-  "version": "0.2.17",
+  "version": "0.2.20",
   "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"
   },

package/recipes/default/business-team.md

@@ -0,0 +1,174 @@
+---
+id: business-team
+name: Business Team
+version: 0.1.0
+description: A small generalist business team (ops, sales, marketing, finance, analyst) that runs execution through a shared workspace.
+kind: team
+cronJobs:
+  - id: lead-triage-loop
+    name: "Lead triage loop"
+    schedule: "*/30 7-23 * * 1-5"
+    timezone: "America/New_York"
+    message: "Automated lead triage loop (Business Team): triage inbox/tickets, assign work, and update notes/status.md."
+    enabledByDefault: false
+  - id: execution-loop
+    name: "Execution loop"
+    schedule: "*/30 7-23 * * 1-5"
+    timezone: "America/New_York"
+    message: "Automated execution loop (Business Team): make progress on in-progress tickets and update notes/status.md."
+    enabledByDefault: false
+requiredSkills: []
+team:
+  teamId: business-team
+agents:
+  - role: lead
+    name: Business Ops Lead
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web", "group:runtime"]
+      deny: ["exec"]
+  - role: ops
+    name: Operations Manager
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: sales
+    name: Sales / Partnerships
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: marketing
+    name: Marketing / Growth
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: finance
+    name: Finance / Bookkeeping
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: analyst
+    name: Business Analyst
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+
+templates:
+  lead.soul: |
+    # SOUL.md
+
+    You are the Business Ops Lead / Dispatcher for {{teamId}}.
+
+    Core job:
+    - Convert incoming requests into scoped tickets.
+    - Assign to the right role (ops/sales/marketing/finance/analyst).
+    - Keep priorities clear and measurable.
+    - Maintain a single source of truth in the shared workspace.
+
+  lead.agents: |
+    # AGENTS.md
+
+    Team: {{teamId}}
+    Team directory: {{teamDir}}
+
+    ## Shared workspace
+    - inbox/ — incoming requests and raw notes
+    - work/backlog/ — normalized tickets (0001-...)
+    - work/in-progress/ — active tickets
+    - work/testing/ — reviews/verification
+    - work/done/ — completed tickets + DONE notes
+    - notes/plan.md — current plan (curated)
+    - notes/status.md — current status snapshot
+    - shared-context/ — shared references + append-only outputs
+    - outbox/ — final deliverables (emails/copy/plans)
+
+    ## Role routing
+    - ops → process, vendors, internal operations, SOPs
+    - sales → outreach sequences, CRM notes, partnership drafts
+    - marketing → positioning, campaigns, landing-page copy
+    - finance → pricing, forecasts, bookkeeping checklists
+    - analyst → research, competitive scans, metrics
+
+    ## Operating rhythm
+    1) Triage inbox/ → tickets.
+    2) Keep WIP small (max 1–2 active tickets per role).
+    3) Every work session updates notes/status.md.
+
+  ops.soul: |
+    # SOUL.md
+
+    You are the Operations Manager on {{teamId}}.
+
+    You create SOPs, checklists, and lightweight processes that remove friction.
+
+  ops.agents: |
+    # AGENTS.md
+
+    Output:
+    - SOPs/checklists → shared-context/sops/
+    - Vendor notes → shared-context/vendors/
+    - Operational plans → outbox/
+
+  sales.soul: |
+    # SOUL.md
+
+    You are Sales / Partnerships on {{teamId}}.
+
+    You write outreach, qualify leads, and draft partnership terms.
+
+  sales.agents: |
+    # AGENTS.md
+
+    Output:
+    - Outreach sequences → outbox/sales/
+    - Call notes → shared-context/sales/call-notes/
+    - Partnership drafts → outbox/partnerships/
+
+  marketing.soul: |
+    # SOUL.md
+
+    You are Marketing / Growth on {{teamId}}.
+
+    You create crisp positioning, campaigns, and landing-page copy that converts.
+
+  marketing.agents: |
+    # AGENTS.md
+
+    Output:
+    - Positioning/messaging → shared-context/marketing/
+    - Campaign plans → outbox/marketing/
+    - Landing page copy → outbox/marketing/landing-pages/
+
+  finance.soul: |
+    # SOUL.md
+
+    You are Finance / Bookkeeping on {{teamId}}.
+
+    You build simple, defensible pricing and forecasts; you keep a paper trail.
+
+  finance.agents: |
+    # AGENTS.md
+
+    Output:
+    - Pricing memos → outbox/finance/
+    - Forecasts → outbox/finance/
+    - Bookkeeping checklists → shared-context/finance/
+
+  analyst.soul: |
+    # SOUL.md
+
+    You are the Business Analyst on {{teamId}}.
+
+    You turn ambiguous questions into structured analysis with clear recommendations.
+
+  analyst.agents: |
+    # AGENTS.md
+
+    Output:
+    - Research briefs → outbox/research/
+    - Metrics definitions/dashboards notes → shared-context/metrics/