@jiggai/recipes 0.2.21 → 0.2.23

package/README.md

@@ -1,7 +1,7 @@
 # ClawRecipes (OpenClaw Recipes Plugin)
 
 <p align="center">
-  <img src="./clawrecipes_cook.jpg" alt="ClawRecipes logo" width="240" />
+  <img src="clawrecipes_cook.jpg" alt="ClawRecipes logo" width="240" />
 </p>
 
 ClawRecipes is an OpenClaw plugin that provides **CLI-first recipes** for scaffolding specialist agents and teams from Markdown.
@@ -134,12 +134,15 @@ Notes:
 ## Links
 - GitHub: https://github.com/JIGGAI/ClawRecipes
 - Docs:
-  - Installation: `docs/INSTALLATION.md`
-  - Commands: `docs/COMMANDS.md`
-  - Recipe format: `docs/RECIPE_FORMAT.md`
-  - Team workflow: `docs/TEAM_WORKFLOW.md`
-
-## What you should be developing (not this plugin)
+  - [Installation](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/INSTALLATION.md): `docs/INSTALLATION.md`
+  - [Commands](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/COMMANDS.md): `docs/COMMANDS.md`
+  - [Recipe format](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/RECIPE_FORMAT.md): `docs/RECIPE_FORMAT.md`
+  - [Team workflow](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/TEAM_WORKFLOW.md): `docs/TEAM_WORKFLOW.md`
+  - [Agents & Skills](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/AGENTS_AND_SKILLS.md): `docs/AGENTS_AND_SKILLS.md`
+  - [Bundled](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/BUNDLED_RECIPES.md): `docs/BUNDLED_RECIPES.md`
+  - [Create Recipe Tutorial](https://github.com/JIGGAI/ClawRecipes/blob/main/docs/TUTORIAL_CREATE_RECIPE.md): `docs/TUTORIAL_CREATE_RECIPE.md`
+
+## Note
 ClawRecipes is meant to be *installed* and then used to build **agents + teams**.
 
 Most users should focus on:

package/docs/AGENTS_AND_SKILLS.md

@@ -38,15 +38,27 @@ In OpenClaw, skills are surfaced as tools the agent can use.
 ## Tool policies (allow/deny)
 Every agent can have a tool policy in OpenClaw config (written via `--apply-config` when scaffolding).
 
-ClawRecipes recipes commonly use:
-- `allow: ["group:fs", "group:web"]` for safe file + web access
-- `allow: ["group:runtime"]` when the agent needs to run local commands
-- `allow: ["group:automation"]` for automation-oriented tools
-- `deny: ["exec"]` for safety on agents that shouldn’t execute commands
-
-The intent:
-- Most agents should **not** have `exec`.
-- Only agents that truly need it (dev/devops) should get runtime/exec capabilities.
+### About `exec`
+`exec` is the shell-command tool. It can be used for things like:
+- running tests/builds (`npm test`, `npm run build`)
+- git operations (`git status`, `git diff`)
+- codegen/migrations (`prisma migrate`, `pnpm lint`)
+- quick diagnostics (`curl`, `jq`, `rg`)
+
+ClawRecipes **does not deny `exec` by default** (many recipes set `deny: []`).
+
+If you want an agent to be able to run commands, you must explicitly allow runtime capabilities.
+
+### Common patterns
+- Safe-by-default agents:
+  - `allow: ["group:fs", "group:web"]`
+  - `deny: ["exec"]` (optional hard block)
+
+- Developer/devops-style agents:
+  - `allow: ["group:fs", "group:web", "group:runtime"]`
+  - `deny: []`
+
+> Note: even when allowed, `exec` may still be gated by your OpenClaw exec approvals / allowlists.
 
 ## How to add/update tool access (allow list)
 There are two common approaches.

package/docs/BUNDLED_RECIPES.md

@@ -29,7 +29,7 @@ Default tool policy (recipe-defined):
 ## 2) `social-team` (team)
 **Kind:** team
 
-**Use when:** you want a multi-role social pipeline: lead + research + writer + editor.
+**Use when:** you want platform-specialist social execution (not copywriting): distribution + listening + platform SEO + community + reporting back to marketing.
 
 Scaffold:
 ```bash
@@ -37,14 +37,19 @@ openclaw recipes scaffold-team social-team --team-id social-team-team --apply-co
 ```
 
 What it creates:
-- `teams/social-team-team/` shared workspace
+- shared team workspace
 - agents:
-  - `agents/social-team-team-lead/`
-  - `agents/social-team-team-research/`
-  - `agents/social-team-team-writer/`
-  - `agents/social-team-team-editor/`
+  - `lead`
+  - `research`
+  - `listening`
+  - `social-seo`
+  - `editorial`
+  - `community`
+  - `distributor`
+  - platform roles: `tiktok`, `instagram`, `youtube`, `facebook`, plus defaults `x`, `linkedin`
 
 Notes:
+- Copy + creative live in `marketing-team` (not here).
 - Default `tools` in the recipe deny `exec` (safer by default).
 
 ## 3) `development-team` (team)
@@ -206,7 +211,7 @@ openclaw recipes scaffold-team marketing-team --team-id marketing-team-team --ap
 ```
 
 Roles:
-- lead, seo, copywriter, ads, social, designer, analyst
+- lead, seo, copywriter, ads, social, designer, analyst, video, compliance
 
 ---
 

package/docs/TEAM_WORKFLOW.md

@@ -61,7 +61,9 @@ Two concepts people often mix up:
 Even if `openclaw recipes dispatch` created an inbox entry + backlog ticket, the lead won’t act unless:
 - a human opens the lead agent/chat, **or**
 - an automation loop runs (cron triage), **or**
-- `main` is allowed to message/spawn the lead agent.
+- a best-effort nudge reaches the lead session.
+
+By default, `openclaw recipes dispatch` will try to **enqueue a system event** to `agent:<teamId>-lead:main` (best-effort). If it can’t, the CLI prints explicit next steps (enable cron / run lead once / allowlist direct pings).
 
 ### Allowlisting other agents (subagents.allowAgents)
 To allow `main` to target team role agents (like `development-team-lead`), add this to your OpenClaw config:

package/index.ts

@@ -782,7 +782,9 @@ const recipesPlugin = {
           console.error("[recipes] ensured agents.list includes main as first/default");
         }
       } catch (e) {
-        console.error(`[recipes] warning: failed to ensure main agent in agents.list: ${(e as Error).message}`);
+        // Keep install/scaffold warning-free; this is non-critical and can fail on locked-down configs.
+        // (If needed, diagnose via debug logs instead of emitting warnings.)
+        console.error(`[recipes] note: failed to ensure main agent in agents.list: ${(e as Error).message}`);
       }
     })();
 
@@ -1357,6 +1359,7 @@ const recipesPlugin = {
               // Best-effort nudge: enqueue a system event for the team lead session.
               // This does not spawn the lead; it ensures that when the lead session runs next,
               // it sees the dispatch immediately.
+              let nudgeQueued = false;
               try {
                 const leadAgentId = `${teamId}-lead`;
                 api.runtime.system.enqueueSystemEvent(
@@ -1369,8 +1372,20 @@ const recipesPlugin = {
                   ].join("\n"),
                   { sessionKey: `agent:${leadAgentId}:main` },
                 );
+                nudgeQueued = true;
               } catch {
-                // ignore: dispatch should still succeed even if system event enqueue fails
+                nudgeQueued = false;
+              }
+
+              if (nudgeQueued) {
+                console.error(`[dispatch] Nudge queued: system event → agent:${teamId}-lead:main`);
+              } else {
+                console.error(`[dispatch] NOTE: Could not auto-nudge ${teamId}-lead (best-effort). Next steps:`);
+                console.error(`- Option A (recommended): ensure the lead triage cron job is installed/enabled (lead-triage-loop).`);
+                console.error(`  - If you declined cron installation during scaffold, re-run scaffold with cron installation enabled, or enable it in settings.`);
+                console.error(`- Option B: manually run/open the lead once so it sees inbox/backlog updates.`);
+                console.error(`- Option C (advanced): allow subagent messaging (if you want direct pings). Add allowAgents in config and restart gateway.`);
+                console.error(`  { agents: { list: [ { id: "main", subagents: { allowAgents: ["${teamId}-lead"] } } ] } }`);
               }
             };
 

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.21",
+  "version": "0.2.22",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiggai/recipes",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "ClawRecipes plugin for OpenClaw (markdown recipes -> scaffold agents/teams)",
   "main": "index.ts",
   "type": "commonjs",
@@ -23,6 +23,7 @@
   ],
   "scripts": {
     "test": "vitest run",
+    "check:bundled-team-recipes": "node scripts/check-bundled-team-recipes.mjs",
     "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",

package/recipes/default/business-team.md

@@ -62,43 +62,78 @@ templates:
   lead.soul: |
     # SOUL.md
 
-    You are the Business Ops Lead / Dispatcher for {{teamId}}.
+    You are the Team 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.
-
+    - Convert new requests into scoped tickets.
+    - Assign work to Dev or DevOps.
+    - Monitor progress and unblock.
+    - Report completions.
   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.
-
+    Shared workspace: {{teamDir}}
+
+    ## Guardrails (read → act → write)
+
+    Before you act:
+    1) Read:
+       - `notes/plan.md`
+       - `notes/status.md`
+       - `shared-context/priorities.md`
+       - the relevant ticket(s)
+
+    After you act:
+    1) Write back:
+       - Update tickets with decisions/assignments.
+       - Keep `notes/status.md` current (3–5 bullets per active ticket).
+
+    ## Curator model
+
+    You are the curator of:
+    - `notes/plan.md`
+    - `shared-context/priorities.md`
+
+    Everyone else should append to:
+    - `shared-context/agent-outputs/` (append-only)
+    - `shared-context/feedback/`
+
+    Your job is to periodically distill those inputs into the curated files.
+
+    ## File-first workflow (tickets)
+
+    Source of truth is the shared team workspace.
+
+    Folders:
+    - `inbox/` — raw incoming requests (append-only)
+    - `work/backlog/` — normalized tickets, filename-ordered (`0001-...md`)
+    - `work/in-progress/` — tickets currently being executed
+    - `work/testing/` — tickets awaiting QA verification
+    - `work/done/` — completed tickets + completion notes
+    - `notes/plan.md` — current plan / priorities (curated)
+    - `notes/status.md` — current status snapshot
+    - `shared-context/` — shared context + append-only outputs
+
+    ### Ticket numbering (critical)
+    - Backlog tickets MUST be named `0001-...md`, `0002-...md`, etc.
+    - The developer pulls the lowest-numbered ticket assigned to them.
+
+    ### Ticket format
+    See `TICKETS.md` in the team root. Every ticket should include:
+    - Context
+    - Requirements
+    - Acceptance criteria
+    - Owner (dev/devops)
+    - Status
+
+    ### Your responsibilities
+    - For every new request in `inbox/`, create a normalized ticket in `work/backlog/`.
+    - Curate `notes/plan.md` and `shared-context/priorities.md`.
+    - Keep `notes/status.md` updated.
+    - When work is ready for QA, move the ticket to `work/testing/` and assign it to the tester.
+    - Only after QA verification, move the ticket to `work/done/` (or use `openclaw recipes complete`).
+    - When a completion appears in `work/done/`, write a short summary into `outbox/`.
   ops.soul: |
     # SOUL.md
 
@@ -109,11 +144,26 @@ templates:
   ops.agents: |
     # AGENTS.md
 
-    Output:
-    - SOPs/checklists → shared-context/sops/
-    - Vendor notes → shared-context/vendors/
-    - Operational plans → outbox/
-
+    Team: {teamId}
+    Shared workspace: {teamDir}
+    Role: ops
+
+    ## Guardrails (read → act → write)
+    Before you act:
+    1) Read:
+       - `notes/plan.md`
+       - `notes/status.md`
+       - relevant ticket(s) in `work/in-progress/`
+       - any relevant shared context under `shared-context/`
+
+    After you act:
+    1) Write back:
+       - Put outputs in the agreed folder (usually `outbox/` or a ticket file).
+       - Update the ticket with what you did and where the artifact is.
+
+    ## Workflow
+    - Prefer a pull model: wait for a clear task from the lead, or propose a scoped task.
+    - Keep work small and reversible.
   sales.soul: |
     # SOUL.md
 
@@ -124,11 +174,26 @@ templates:
   sales.agents: |
     # AGENTS.md
 
-    Output:
-    - Outreach sequences → outbox/sales/
-    - Call notes → shared-context/sales/call-notes/
-    - Partnership drafts → outbox/partnerships/
-
+    Team: {teamId}
+    Shared workspace: {teamDir}
+    Role: sales
+
+    ## Guardrails (read → act → write)
+    Before you act:
+    1) Read:
+       - `notes/plan.md`
+       - `notes/status.md`
+       - relevant ticket(s) in `work/in-progress/`
+       - any relevant shared context under `shared-context/`
+
+    After you act:
+    1) Write back:
+       - Put outputs in the agreed folder (usually `outbox/` or a ticket file).
+       - Update the ticket with what you did and where the artifact is.
+
+    ## Workflow
+    - Prefer a pull model: wait for a clear task from the lead, or propose a scoped task.
+    - Keep work small and reversible.
   marketing.soul: |
     # SOUL.md
 
@@ -139,11 +204,26 @@ templates:
   marketing.agents: |
     # AGENTS.md
 
-    Output:
-    - Positioning/messaging → shared-context/marketing/
-    - Campaign plans → outbox/marketing/
-    - Landing page copy → outbox/marketing/landing-pages/
-
+    Team: {teamId}
+    Shared workspace: {teamDir}
+    Role: marketing
+
+    ## Guardrails (read → act → write)
+    Before you act:
+    1) Read:
+       - `notes/plan.md`
+       - `notes/status.md`
+       - relevant ticket(s) in `work/in-progress/`
+       - any relevant shared context under `shared-context/`
+
+    After you act:
+    1) Write back:
+       - Put outputs in the agreed folder (usually `outbox/` or a ticket file).
+       - Update the ticket with what you did and where the artifact is.
+
+    ## Workflow
+    - Prefer a pull model: wait for a clear task from the lead, or propose a scoped task.
+    - Keep work small and reversible.
   finance.soul: |
     # SOUL.md
 
@@ -154,11 +234,26 @@ templates:
   finance.agents: |
     # AGENTS.md
 
-    Output:
-    - Pricing memos → outbox/finance/
-    - Forecasts → outbox/finance/
-    - Bookkeeping checklists → shared-context/finance/
-
+    Team: {teamId}
+    Shared workspace: {teamDir}
+    Role: finance
+
+    ## Guardrails (read → act → write)
+    Before you act:
+    1) Read:
+       - `notes/plan.md`
+       - `notes/status.md`
+       - relevant ticket(s) in `work/in-progress/`
+       - any relevant shared context under `shared-context/`
+
+    After you act:
+    1) Write back:
+       - Put outputs in the agreed folder (usually `outbox/` or a ticket file).
+       - Update the ticket with what you did and where the artifact is.
+
+    ## Workflow
+    - Prefer a pull model: wait for a clear task from the lead, or propose a scoped task.
+    - Keep work small and reversible.
   analyst.soul: |
     # SOUL.md
 
@@ -172,3 +267,23 @@ templates:
     Output:
     - Research briefs → outbox/research/
     - Metrics definitions/dashboards notes → shared-context/metrics/
+
+---
+
+# Business Team Recipe
+
+Bundled team recipe.
+
+## Files
+- Creates a shared team workspace under `~/.openclaw/workspace-<teamId>/` (example: `~/.openclaw/workspace-business-team-team/`).
+- Creates per-role directories under `roles/<role>/` for: `SOUL.md`, `AGENTS.md`, `TOOLS.md`, `STATUS.md`, `NOTES.md`.
+- Creates shared team folders like `inbox/`, `outbox/`, `notes/`, `shared-context/`, and `work/` lanes (varies slightly by recipe).
+
+## Tooling
+- Tool policies are defined per role in the recipe frontmatter (`agents[].tools`).
+- Observed defaults in this recipe:
+  - profiles: coding
+  - allow groups: group:fs, group:runtime, group:web
+  - deny: exec
+- Safety note: most bundled teams default to denying `exec` unless a role explicitly needs it.
+