@jiggai/recipes 0.2.20 → 0.2.22

package/docs/BUNDLED_RECIPES.md

@@ -195,9 +195,24 @@ Default tool policy:
 
 ---
 
+# Teams
+
+## 11) `marketing-team` (team)
+**Use when:** you want a full marketing execution loop: SEO + copy + ads + social + design + analytics.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team marketing-team --team-id marketing-team-team --apply-config
+```
+
+Roles:
+- lead, seo, copywriter, ads, social, designer, analyst
+
+---
+
 # Vertical packs (bundled team recipes)
 
-## 11) `business-team` (team)
+## 12) `business-team` (team)
 **Use when:** you want a general-purpose business execution team.
 
 Scaffold:
@@ -208,7 +223,7 @@ openclaw recipes scaffold-team business-team --team-id business-team-team --appl
 Roles:
 - lead, ops, sales, marketing, finance, analyst
 
-## 12) `law-firm-team` (team)
+## 13) `law-firm-team` (team)
 **Use when:** you want a legal practice workflow: intake → research → drafting → compliance.
 
 Scaffold:
@@ -219,7 +234,7 @@ openclaw recipes scaffold-team law-firm-team --team-id law-firm-team-team --appl
 Roles:
 - lead, intake, researcher, drafter, compliance, ops
 
-## 13) `clinic-team` (team)
+## 14) `clinic-team` (team)
 **Use when:** you want a clinic ops workflow: intake/scheduling/billing/compliance/patient education.
 
 Scaffold:
@@ -230,7 +245,7 @@ openclaw recipes scaffold-team clinic-team --team-id clinic-team-team --apply-co
 Roles:
 - lead, intake, scheduler, billing, compliance, educator
 
-## 14) `construction-team` (team)
+## 15) `construction-team` (team)
 **Use when:** you want a construction delivery workflow: PM/estimation/scheduling/safety/procurement.
 
 Scaffold:
@@ -241,7 +256,7 @@ openclaw recipes scaffold-team construction-team --team-id construction-team-tea
 Roles:
 - lead, pm, estimator, scheduler, safety, procurement
 
-## 15) `financial-planner-team` (team)
+## 16) `financial-planner-team` (team)
 **Use when:** you want a financial planning practice workflow.
 
 Scaffold:
@@ -252,7 +267,7 @@ openclaw recipes scaffold-team financial-planner-team --team-id financial-planne
 Roles:
 - lead, advisor, analyst, tax, insurance, ops
 
-## 16) `stock-trader-team` (team)
+## 17) `stock-trader-team` (team)
 **Use when:** you want a trading workflow: research/signals/risk/journaling.
 
 Scaffold:
@@ -263,7 +278,7 @@ openclaw recipes scaffold-team stock-trader-team --team-id stock-trader-team-tea
 Roles:
 - lead, researcher, signals, risk, journal, ops
 
-## 17) `crypto-trader-team` (team)
+## 18) `crypto-trader-team` (team)
 **Use when:** you want a crypto trading workflow with onchain research.
 
 Scaffold:

package/docs/TEAM_WORKFLOW.md

@@ -24,25 +24,67 @@ When you scaffold a team:
 1) **Intake**
 - New requests land in `inbox/`.
 
-2) **Plan**
+2) **(Optional) Nudge / automation**
+- A cron job can periodically ping the team lead to triage `inbox/` and keep work moving.
+
+3) **Plan / triage (lead)**
 - Convert the request into a numbered ticket in `work/backlog/`.
+- Fill out: Context, Requirements, Acceptance Criteria, Tasks, Owner, Status, and verification steps.
+- **Every ticket must include a `## Comments` section.** Agents must check/respond to comments on tickets they’re assigned to **or** where they are mentioned via `@<agentname>`.
 - Filename ordering is the priority queue.
 
-3) **Execute**
+4) **Execute (dev/devops)**
 - Move ticket file to `work/in-progress/` (or use `take`).
 - Do work; write artifacts into `shared/` or agent workspaces.
 
-4) **Test**
+5) **Test**
 - Move ticket to `work/testing/`.
 - Assign `Owner: test` (or explicitly tag the tester role) and include clear “Verification steps” in the ticket.
 - Tester verifies and either:
   - moves to `work/done/` (pass), or
   - bounces back to `work/in-progress/` with a bug note (fail)
 
-5) **Complete**
+6) **Complete**
 - Move ticket to `work/done/` (or use `complete`).
 - Add `Completed:` timestamp (automated by `complete` or `move-ticket --completed`).
 
+## Sub-agents + waking up the lead (important)
+Two concepts people often mix up:
+
+1) **Chatting with a role agent directly**
+- If an agent id exists (configured under `agents.list`), you can start a chat with it directly via UI/CLI.
+
+2) **Asking one agent (usually `main`) to wake/spawn/ping another agent**
+- This uses sub-agent/session tooling, and is gated by the requester’s allowlist.
+
+### Why the lead sometimes “never picks it 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.
+
+### Allowlisting other agents (subagents.allowAgents)
+To allow `main` to target team role agents (like `development-team-lead`), add this to your OpenClaw config:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        subagents: {
+          allowAgents: ["development-team-lead"], // or ["*"] for any configured agent
+        },
+      },
+    ],
+  },
+}
+```
+
+Then restart the gateway.
+
+Tip: use the `agents_list` tool to see what’s currently allowed.
+
 ## Dispatcher command
 The lead can convert a natural-language request into artifacts with:
 

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}`);
       }
     })();
 
@@ -1330,7 +1332,7 @@ const recipesPlugin = {
 
             const inboxMd = `# Inbox — ${teamId}\n\nReceived: ${receivedIso}\n\n## Request\n${requestText}\n\n## Proposed work\n- Ticket: ${ticketNumStr}-${baseSlug}\n- Owner: ${owner}\n\n## Links\n- Ticket: ${path.relative(teamDir, ticketPath)}\n- Assignment: ${path.relative(teamDir, assignmentPath)}\n`;
 
-            const ticketMd = `# ${ticketNumStr}-${baseSlug}\n\nCreated: ${receivedIso}\nOwner: ${owner}\nStatus: queued\nInbox: ${path.relative(teamDir, inboxPath)}\nAssignment: ${path.relative(teamDir, assignmentPath)}\n\n## Context\n${requestText}\n\n## Requirements\n- (fill in)\n\n## Acceptance criteria\n- (fill in)\n\n## Tasks\n- [ ] (fill in)\n`;
+            const ticketMd = `# ${ticketNumStr}-${baseSlug}\n\nCreated: ${receivedIso}\nOwner: ${owner}\nStatus: queued\nInbox: ${path.relative(teamDir, inboxPath)}\nAssignment: ${path.relative(teamDir, assignmentPath)}\n\n## Context\n${requestText}\n\n## Requirements\n- (fill in)\n\n## Acceptance criteria\n- (fill in)\n\n## Tasks\n- [ ] (fill in)\n\n## Comments\n- (use this section for @mentions, questions, decisions, and dated replies)\n`;
 
             const assignmentMd = `# Assignment — ${ticketNumStr}-${baseSlug}\n\nCreated: ${receivedIso}\nAssigned: ${owner}\n\n## Goal\n${title}\n\n## Ticket\n${path.relative(teamDir, ticketPath)}\n\n## Notes\n- Created by: openclaw recipes dispatch\n`;
 
@@ -1353,6 +1355,25 @@ const recipesPlugin = {
               await writeFileSafely(inboxPath, inboxMd, "createOnly");
               await writeFileSafely(ticketPath, ticketMd, "createOnly");
               await writeFileSafely(assignmentPath, assignmentMd, "createOnly");
+
+              // 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.
+              try {
+                const leadAgentId = `${teamId}-lead`;
+                api.runtime.system.enqueueSystemEvent(
+                  [
+                    `Dispatch created new intake for team: ${teamId}`,
+                    `- Inbox: ${path.relative(teamDir, inboxPath)}`,
+                    `- Backlog: ${path.relative(teamDir, ticketPath)}`,
+                    `- Assignment: ${path.relative(teamDir, assignmentPath)}`,
+                    `Action: please triage/normalize the ticket (fill Requirements/AC/tasks) and move it through the workflow.`,
+                  ].join("\n"),
+                  { sessionKey: `agent:${leadAgentId}:main` },
+                );
+              } catch {
+                // ignore: dispatch should still succeed even if system event enqueue fails
+              }
             };
 
             if (options.yes) {

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jiggai/recipes",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "ClawRecipes plugin for OpenClaw (markdown recipes -> scaffold agents/teams)",
   "main": "index.ts",
   "type": "commonjs",

package/recipes/default/development-team.md

@@ -9,8 +9,8 @@ cronJobs:
     name: "Lead triage loop"
     schedule: "*/30 7-23 * * 1-5"
     timezone: "America/New_York"
-    message: "Automated lead triage loop: triage inbox/tickets, assign work, and update notes/status.md."
-    enabledByDefault: false
+    message: "Automated lead triage loop: triage inbox/tickets, assign work, and update notes/status.md. Anti-stuck: if lowest in-progress is HARD BLOCKED, advance the next unblocked ticket (or pull from backlog). If in-progress is stale (>12h no dated update), comment or move it back."
+    enabledByDefault: true
   - id: execution-loop
     name: "Execution loop"
     schedule: "*/30 7-23 * * 1-5"

package/recipes/default/marketing-team.md

@@ -0,0 +1,276 @@
+---
+id: marketing-team
+name: Marketing Team
+version: 0.1.0
+description: A marketing execution team (SEO, copy, ads, social, design, analytics) coordinated via 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 (Marketing 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 (Marketing Team): make progress on in-progress tickets and update notes/status.md."
+    enabledByDefault: false
+requiredSkills: []
+team:
+  teamId: marketing-team
+agents:
+  - role: lead
+    name: Marketing Lead
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web", "group:runtime"]
+      deny: ["exec"]
+  - role: seo
+    name: SEO Strategist
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: copywriter
+    name: Copywriter
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: ads
+    name: Paid Ads Specialist
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: social
+    name: Social & Community
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: designer
+    name: Creative / Designer
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+  - role: analyst
+    name: Marketing Analyst
+    tools:
+      profile: "coding"
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+
+templates:
+  lead.soul: |
+    # SOUL.md
+
+    You are the Marketing Lead / Dispatcher for {{teamId}}.
+
+    Core job:
+    - Turn growth goals into an execution plan (channels, messaging, experiments).
+    - Convert requests into scoped tickets with measurable acceptance criteria.
+    - Keep a single source of truth in the shared workspace.
+    - Ship work that improves outcomes (traffic, activation, retention, revenue).
+
+  lead.agents: |
+    # AGENTS.md
+
+    Team: {{teamId}}
+    Team directory: {{teamDir}}
+
+    ## Workflow (file-first)
+    - Inbox → tickets → execution → review → done.
+    - Keep WIP small and measurable.
+
+    ## Shared workspace
+    - inbox/ — incoming requests, raw notes
+    - work/backlog/ — tickets (0001-...)
+    - work/in-progress/ — active tickets
+    - work/testing/ — review/verification
+    - work/done/ — completed work + DONE notes
+    - notes/plan.md — current plan (curated)
+    - notes/status.md — current status snapshot (3–7 bullets)
+    - notes/GOALS.md + notes/goals/ — goals index + goal docs
+    - shared-context/ — canonical shared context + append-only outputs
+    - outbox/ — final deliverables (copy, briefs, reports)
+
+    ## Role routing
+    - seo → keyword strategy, content briefs, technical SEO audits
+    - copywriter → landing pages, emails, ads copy, messaging
+    - ads → campaign structure, targeting, creative testing plan
+    - social → content calendar, community replies, distribution
+    - designer → creative specs, visual systems, asset checklists
+    - analyst → reporting, funnel analysis, experiment readouts
+
+    ## Quality bar
+    Every ticket should end with:
+    - what changed
+    - how to measure impact
+    - where the artifacts live (links/paths)
+
+  seo.soul: |
+    # SOUL.md
+
+    You are the SEO Strategist on {{teamId}}.
+
+    You improve organic acquisition via keyword strategy, content briefs, and technical SEO hygiene.
+
+  seo.agents: |
+    # AGENTS.md
+
+    Output conventions:
+    - Keyword lists + clustering → outbox/seo/keywords/
+    - Content briefs → outbox/seo/briefs/
+    - Technical audit notes → outbox/seo/technical/
+
+    Brief checklist:
+    - target keyword + intent
+    - suggested title/H1
+    - outline + sections
+    - internal links to add
+    - FAQs / schema ideas
+
+  copywriter.soul: |
+    # SOUL.md
+
+    You are the Copywriter on {{teamId}}.
+
+    You write clear, conversion-oriented copy that matches the product’s positioning.
+
+  copywriter.agents: |
+    # AGENTS.md
+
+    Output conventions:
+    - Landing page copy → outbox/copy/landing-pages/
+    - Email sequences → outbox/copy/email/
+    - Ad copy variants → outbox/copy/ads/
+
+    Checklist:
+    - audience + pain
+    - value prop + proof
+    - CTA + objections
+
+  ads.soul: |
+    # SOUL.md
+
+    You are the Paid Ads Specialist on {{teamId}}.
+
+    You propose campaigns and experiments with clear budgets, targeting, and success metrics.
+
+  ads.agents: |
+    # AGENTS.md
+
+    Output conventions:
+    - Campaign plans → outbox/ads/campaigns/
+    - Creative test matrices → outbox/ads/creative-tests/
+    - Landing page requirements → outbox/ads/landing-page-notes/
+
+    Checklist:
+    - objective + KPI
+    - targeting hypothesis
+    - creative variants
+    - measurement plan
+
+  social.soul: |
+    # SOUL.md
+
+    You run Social & Community for {{teamId}}.
+
+    You create distribution plans and keep a consistent brand voice.
+
+  social.agents: |
+    # AGENTS.md
+
+    Output conventions:
+    - Social calendar → outbox/social/calendar/
+    - Draft posts → outbox/social/posts/
+    - Community reply macros → outbox/social/replies/
+
+    Checklist:
+    - hook
+    - core point
+    - CTA
+    - link target
+
+  designer.soul: |
+    # SOUL.md
+
+    You are Creative / Designer on {{teamId}}.
+
+    You turn briefs into clear creative specs and asset checklists.
+
+  designer.agents: |
+    # AGENTS.md
+
+    Output conventions:
+    - Creative briefs/specs → outbox/creative/briefs/
+    - Asset checklists → outbox/creative/assets/
+    - Brand/visual notes → shared-context/creative/
+
+    Checklist:
+    - format + dimensions
+    - message hierarchy
+    - variant list
+    - delivery deadline
+
+  analyst.soul: |
+    # SOUL.md
+
+    You are the Marketing Analyst on {{teamId}}.
+
+    You build simple reporting that answers: what changed, why, and what to do next.
+
+  analyst.agents: |
+    # AGENTS.md
+
+    Output conventions:
+    - Dashboards/metric definitions → shared-context/metrics/
+    - Weekly reports → outbox/analytics/weekly/
+    - Experiment readouts → outbox/analytics/experiments/
+
+    Checklist:
+    - baseline vs current
+    - segments
+    - confounders
+    - recommendation
+
+files:
+  - path: SOUL.md
+    template: soul
+    mode: createOnly
+  - path: AGENTS.md
+    template: agents
+    mode: createOnly
+  - path: TOOLS.md
+    template: tools
+    mode: createOnly
+  - path: STATUS.md
+    template: status
+    mode: createOnly
+  - path: NOTES.md
+    template: notes
+    mode: createOnly
+
+tools:
+  profile: "coding"
+  allow: ["group:fs", "group:web"]
+  deny: ["exec"]
+---
+# Marketing Team Recipe
+
+Scaffolds a shared marketing workspace plus roles for SEO, copy, ads, social, design, and analytics.
+
+## What you get
+- Shared workspace at `~/.openclaw/workspace-<teamId>/`
+- Roles under `roles/<role>/` with namespaced agents
+- File-first tickets: backlog → in-progress → testing → done
+
+## Typical outputs
+- Content briefs + landing page copy
+- Paid campaign plans + creative test matrices
+- Social calendar + post drafts
+- Weekly reporting + experiment readouts