@jiggai/recipes 0.2.11

package/docs/COMMANDS.md

@@ -0,0 +1,266 @@
+# Command reference
+
+All commands live under:
+
+```bash
+openclaw recipes <command>
+```
+
+## `list`
+List available recipes (builtin + workspace).
+
+```bash
+openclaw recipes list
+```
+
+Outputs JSON rows:
+- `id`, `name`, `kind`, `source`
+
+## `show <id>`
+Print the raw recipe markdown.
+
+```bash
+openclaw recipes show development-team
+```
+
+## `status [id]`
+Check missing skills for a recipe (or all recipes).
+
+```bash
+openclaw recipes status
+openclaw recipes status development-team
+```
+
+## `scaffold <recipeId>`
+Scaffold a single agent workspace from an **agent** recipe.
+
+```bash
+openclaw recipes scaffold project-manager --agent-id pm --name "Project Manager" --apply-config
+```
+
+Options:
+- `--agent-id <id>` (required)
+- `--name <name>`
+- `--overwrite` (overwrite recipe-managed files)
+- `--apply-config` (write/update `agents.list[]` in OpenClaw config)
+
+## `scaffold-team <recipeId>`
+
+### Cron installation config
+If a recipe declares `cronJobs`, scaffold will reconcile those jobs using the plugin config key:
+- `plugins.entries.recipes.config.cronInstallation`: `off | prompt | on`
+  - `off`: never install/reconcile
+  - `prompt` (default): prompt each run (default answer is **No**)
+  - `on`: install/reconcile; new jobs follow `enabledByDefault`
+Scaffold a shared **team workspace** + multiple agents from a **team** recipe.
+
+```bash
+openclaw recipes scaffold-team development-team \
+  --team-id development-team-team \
+  --overwrite \
+  --apply-config
+```
+
+Options:
+- `--team-id <teamId>` (required)
+  - **Must end with `-team`** (enforced)
+- `--overwrite`
+- `--apply-config`
+
+Creates a shared team workspace root:
+
+- `~/.openclaw/workspace-<teamId>/...`
+
+Standard folders:
+- `inbox/`, `outbox/`, `shared/`, `notes/`
+- `work/{backlog,in-progress,testing,done,assignments}`
+- `roles/<role>/...` (role-specific recipe files)
+
+Also creates agent config entries under `agents.list[]` (when `--apply-config`), with agent ids:
+- `<teamId>-<role>`
+
+## `install <idOrSlug> [--yes]`
+Install skills from ClawHub (confirmation-gated).
+
+Default behavior: **global install** into `~/.openclaw/skills`.
+
+```bash
+# Global (shared across all agents)
+openclaw recipes install agentchat --yes
+
+# Agent-scoped (into workspace-<agentId>/skills)
+openclaw recipes install agentchat --yes --agent-id dev
+
+# Team-scoped (into workspace-<teamId>/skills)
+openclaw recipes install agentchat --yes --team-id development-team-team
+```
+
+Behavior:
+- If `idOrSlug` matches a recipe id, installs that recipe’s `requiredSkills` + `optionalSkills`.
+- Otherwise treats it as a ClawHub skill slug.
+- Installs via:
+  - `npx clawhub@latest --workdir <targetWorkspace> --dir skills install <slug>` (agent/team)
+  - `npx clawhub@latest --workdir ~/.openclaw --dir skills install <slug>` (global)
+- Confirmation-gated unless `--yes`.
+- In non-interactive mode (no TTY), requires `--yes`.
+
+## `bind`
+Add/update a multi-agent routing binding (writes `bindings[]` in `~/.openclaw/openclaw.json`).
+
+Examples:
+
+```bash
+# Route one Telegram DM to an agent
+openclaw recipes bind --agent-id dev --channel telegram --peer-kind dm --peer-id 6477250615
+
+# Route all Telegram traffic to an agent (broad match)
+openclaw recipes bind --agent-id dev --channel telegram
+```
+
+Notes:
+- `peer.kind` must be one of: `dm|group|channel`.
+- Peer-specific bindings are inserted first (more specific wins).
+
+## `unbind`
+Remove routing binding(s) from OpenClaw config (`bindings[]`).
+
+Examples:
+
+```bash
+# Remove a specific DM binding for an agent
+openclaw recipes unbind --agent-id dev --channel telegram --peer-kind dm --peer-id 6477250615
+
+# Remove ALL bindings that match this peer (any agent)
+openclaw recipes unbind --channel telegram --peer-kind dm --peer-id 6477250615
+```
+
+## `bindings`
+Print the current `bindings[]` from OpenClaw config.
+
+```bash
+openclaw recipes bindings
+```
+
+## `migrate-team`
+Migrate a legacy team scaffold into the new `workspace-<teamId>` layout.
+
+```bash
+openclaw recipes migrate-team --team-id development-team-team --dry-run
+openclaw recipes migrate-team --team-id development-team-team --mode move
+```
+
+Options:
+- `--dry-run`
+- `--mode move|copy`
+- `--overwrite` (merge into existing destination)
+
+## `dispatch`
+Convert a natural-language request into file-first execution artifacts.
+
+## `tickets`
+List tickets for a team across the standard workflow stages.
+
+```bash
+openclaw recipes tickets --team-id <teamId>
+openclaw recipes tickets --team-id <teamId> --json
+```
+
+## `cleanup-workspaces`
+List (dry-run, default) or delete (with `--yes`) temporary test/scaffold team workspaces under your OpenClaw home directory.
+
+Safety rails:
+- Only considers `workspace-<teamId>` directories where `<teamId>`:
+  - ends with `-team`
+  - starts with an allowed prefix (default: `smoke-`, `qa-`, `tmp-`, `test-`)
+- Refuses symlinks
+- Protected teams (at minimum: `development-team`) are never deleted
+
+Examples:
+```bash
+# Dry-run (default): list what would be deleted
+openclaw recipes cleanup-workspaces
+
+# Actually delete eligible workspaces
+openclaw recipes cleanup-workspaces --yes
+
+# Custom prefixes (repeatable)
+openclaw recipes cleanup-workspaces --prefix smoke- --prefix qa- --yes
+
+# JSON output
+openclaw recipes cleanup-workspaces --json
+```
+
+## `move-ticket`
+Move a ticket file between workflow stages and update the ticket’s `Status:` field.
+
+```bash
+openclaw recipes move-ticket --team-id <teamId> --ticket 0007 --to in-progress
+openclaw recipes move-ticket --team-id <teamId> --ticket 0007 --to testing
+openclaw recipes move-ticket --team-id <teamId> --ticket 0007 --to done --completed
+```
+
+Stages:
+- `backlog` → `Status: queued`
+- `in-progress` → `Status: in-progress`
+- `testing` → `Status: testing`
+- `done` → `Status: done` (optional `Completed:` timestamp)
+
+## `assign`
+Assign a ticket to an owner (updates `Owner:` and creates an assignment stub).
+
+```bash
+openclaw recipes assign --team-id <teamId> --ticket 0007 --owner dev
+openclaw recipes assign --team-id <teamId> --ticket 0007 --owner lead
+```
+
+Owners (current): `dev|devops|lead|test`.
+
+## `take`
+Shortcut: assign + move to in-progress.
+
+```bash
+openclaw recipes take --team-id <teamId> --ticket 0007 --owner dev
+```
+
+## `handoff`
+QA handoff in one step: move a ticket to `work/testing/`, set `Status: testing`, assign to a tester (default `test`), and write/update the assignment stub.
+
+```bash
+openclaw recipes handoff --team-id <teamId> --ticket 0007
+openclaw recipes handoff --team-id <teamId> --ticket 0007 --tester test
+```
+
+Notes:
+- Creates `work/testing/` if missing.
+- Idempotent: if the ticket is already in `work/testing/`, it won’t re-move it; it will ensure fields + assignment stub.
+
+## `complete`
+Shortcut: move to done + ensure `Status: done` + add `Completed:` timestamp.
+
+```bash
+openclaw recipes complete --team-id <teamId> --ticket 0007
+```
+
+```bash
+openclaw recipes dispatch \
+  --team-id development-team-team \
+  --request "Add a customer-support team recipe" \
+  --owner lead
+```
+
+Options:
+- `--team-id <teamId>` (required)
+- `--request <text>` (optional; prompts in TTY)
+- `--owner dev|devops|lead|test` (default: `dev`)
+- `--yes` (skip review prompt)
+
+Creates (createOnly):
+- `workspace-<teamId>/inbox/<timestamp>-<slug>.md`
+- `workspace-<teamId>/work/backlog/<NNNN>-<slug>.md`
+- `workspace-<teamId>/work/assignments/<NNNN>-assigned-<owner>.md`
+
+Ticket numbering:
+- Scans `work/backlog`, `work/in-progress`, `work/testing`, `work/done` and uses max+1.
+
+Review-before-write:
+- Prints a JSON plan and asks for confirmation unless `--yes`.

package/docs/INSTALLATION.md

@@ -0,0 +1,80 @@
+# Installation
+
+This repo is an **OpenClaw plugin** (not a standalone CLI). OpenClaw loads it and exposes the commands under:
+
+- `openclaw recipes ...`
+
+## Prerequisites
+- OpenClaw installed and working (`openclaw --version`)
+- Node.js available (OpenClaw uses Node to load plugins)
+- (For `recipes install`) you’ll need access to ClawHub (the command runs `npx clawhub@latest ...`).
+
+## Install
+### Option A (preferred): install from npm
+Once published, you can install directly via npm:
+
+```bash
+openclaw plugins install @jiggai/recipes
+openclaw gateway restart
+openclaw plugins list
+```
+
+### Option B: install from GitHub
+```bash
+git clone https://github.com/JIGGAI/ClawRecipes.git ~/clawrecipes
+openclaw plugins install --link ~/clawrecipes
+openclaw gateway restart
+openclaw plugins list
+```
+
+### Option B: already cloned
+```bash
+openclaw plugins install --link ~/clawrecipes
+openclaw gateway restart
+openclaw plugins list
+```
+
+Confirm it loaded:
+```bash
+openclaw plugins list
+# look for id: recipes
+```
+
+4) Try a basic command:
+```bash
+openclaw recipes list
+```
+
+## Updating the plugin
+If you pull a newer version from GitHub, restart the gateway so OpenClaw reloads the plugin:
+
+```bash
+cd ~/clawrecipes
+git pull
+openclaw gateway restart
+```
+
+## Uninstall / disable
+If installed via local path, remove the plugin install entry and restart:
+
+```bash
+openclaw plugins uninstall recipes
+openclaw gateway restart
+```
+
+(If `plugins uninstall` is not available in your build, remove the path from your OpenClaw config’s plugin load paths and restart.)
+
+## Troubleshooting
+### Plugin loads but commands are missing
+- Restart: `openclaw gateway restart`
+- Check: `openclaw plugins list`
+- Verify `openclaw.plugin.json` exists at repo root and has `id: "recipes"`.
+
+### `recipes install` fails
+- Run `npx clawhub@latest --help` to confirm the CLI can run.
+- Ensure you are logged into ClawHub if required (`npx clawhub@latest login`).
+- Confirm the install scope you intended:
+  - global: `~/.openclaw/skills/<skill>`
+  - agent: `~/.openclaw/workspace-<agentId>/skills/<skill>`
+  - team: `~/.openclaw/workspace-<teamId>/skills/<skill>`
+- If you change installs or config, restart: `openclaw gateway restart`.

package/docs/RECIPE_FORMAT.md

@@ -0,0 +1,127 @@
+# Recipe format
+
+Recipes are Markdown files with YAML frontmatter.
+
+They can be:
+- **agent** recipes: scaffold a single agent workspace
+- **team** recipes: scaffold a team workspace and multiple agents
+
+## File locations
+Recipes are discovered from:
+- Built-in: `recipes/default/*.md` inside this plugin
+- Workspace-local: `<workspaceRoot>/recipes/*.md` (default)
+
+## Frontmatter (common)
+```yaml
+---
+id: development-team
+name: Development Team
+kind: team # or agent
+version: 0.1.0
+description: ...
+
+requiredSkills:
+  - some-skill
+optionalSkills:
+  - another-skill
+---
+```
+
+### `requiredSkills` / `optionalSkills`
+These are **ClawHub skill slugs**.
+
+They’re used by:
+- `openclaw recipes status` (detect missing skills)
+- `openclaw recipes install <recipeId>` (install the listed skills)
+
+## Agent recipes
+Agent recipes use templates + files.
+
+### `templates`
+A string map of template keys → template bodies.
+
+### `files`
+Each file entry writes a file under the agent’s workspace:
+
+```yaml
+files:
+  - path: SOUL.md
+    template: soul
+    mode: createOnly # or overwrite
+```
+
+Template rendering:
+- Simple `{{var}}` replacement.
+- No conditionals / no code execution.
+
+Common vars:
+- `agentId`
+- `agentName`
+
+## Team recipes
+Team recipes define a team plus multiple agents:
+
+```yaml
+team:
+  teamId: development-team
+  name: Development Team
+
+agents:
+  - role: lead
+    name: Dev Team Lead
+  - role: dev
+    name: Software Engineer
+  - role: devops
+    name: DevOps / SRE
+```
+
+### Team ID and agent IDs
+- **Team IDs must end with `-team`** (enforced by `scaffold-team`).
+- Agent IDs default to: `<teamId>-<role>`
+
+### Template namespacing for teams
+For team recipes, file templates are namespaced by role:
+- `lead.soul`, `dev.soul`, etc.
+
+If a `files[].template` key does not contain a `.`, ClawRecipes prefixes it with `<role>.`.
+
+## Cron jobs (optional)
+Recipes can optionally declare cron jobs to be reconciled during `scaffold` / `scaffold-team`.
+
+```yaml
+cronJobs:
+  - id: daily-review
+    schedule: "0 14 * * 1-5"  # 5-field cron
+    message: "Daily review: summarize inbox + calendar for today."
+    enabledByDefault: false
+    timezone: "America/New_York"   # optional
+    channel: "telegram"            # optional (default: last)
+    to: "<chatId or phone>"        # optional
+    description: "Weekday daily review"
+```
+
+Notes:
+- `cronJobs[].id` must be **stable** within the recipe; it’s used for idempotent updates.
+- Safe default behavior is conservative: when `cronInstallation=prompt`, the prompt default is **No**.
+- When the user opts out, jobs are installed **disabled** (so they can be enabled later).
+
+## Tool policy
+Recipes can include tool policy, which is written into `agents.list[].tools` when `--apply-config` is used:
+
+```yaml
+tools:
+  profile: coding
+  allow:
+    - group:fs
+    - group:web
+    - group:runtime
+  deny: []
+```
+
+Team recipes can override tools per-agent via `agents[].tools`.
+
+## Recommended conventions
+- Keep `requiredSkills` minimal; use `optionalSkills` for “nice to have”.
+- For teams, use file-first work queues:
+  - `work/backlog/0001-...md` style tickets
+  - filename ordering is the queue ordering

package/docs/TEAM_WORKFLOW.md

@@ -0,0 +1,62 @@
+# Team workflow (file-first)
+
+ClawRecipes’ differentiator is the **shared team workspace** + a simple, durable, file-first workflow.
+
+## Team workspace structure
+When you scaffold a team:
+
+```
+~/.openclaw/workspace-<teamId>/
+  inbox/
+  outbox/
+  shared/
+  notes/
+  work/
+    backlog/
+    in-progress/
+    testing/
+    done/
+    assignments/
+  TEAM.md
+```
+
+## The loop
+1) **Intake**
+- New requests land in `inbox/`.
+
+2) **Plan**
+- Convert the request into a numbered ticket in `work/backlog/`.
+- Filename ordering is the priority queue.
+
+3) **Execute**
+- Move ticket file to `work/in-progress/` (or use `take`).
+- Do work; write artifacts into `shared/` or agent workspaces.
+
+4) **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**
+- Move ticket to `work/done/` (or use `complete`).
+- Add `Completed:` timestamp (automated by `complete` or `move-ticket --completed`).
+
+## Dispatcher command
+The lead can convert a natural-language request into artifacts with:
+
+```bash
+openclaw recipes dispatch --team-id <teamId> --request "..." --owner dev
+```
+
+This creates:
+- an inbox entry
+- a backlog ticket
+- an assignment stub
+
+## Why file-first?
+- Works offline
+- Easy to version control
+- Easy to audit and search
+- Doesn’t depend on any single UI

package/docs/TUTORIAL_CREATE_RECIPE.md

@@ -0,0 +1,151 @@
+# Tutorial: create your first recipe
+
+This tutorial shows how to create a **team recipe** (shared workspace + multiple agents).
+
+You’ll learn:
+- where recipes live
+- how frontmatter works
+- how templates/files are written
+- how to scaffold a team and run the file-first workflow
+
+## Step 0 — confirm ClawRecipes is installed
+```bash
+openclaw plugins list
+openclaw recipes list
+```
+
+## Step 1 — create a recipe file in your OpenClaw workspace
+Create:
+
+- `~/.openclaw/workspace/recipes/my-first-team.md`
+
+Minimal example:
+
+```md
+---
+id: my-first-team
+name: My First Team
+kind: team
+version: 0.1.0
+description: A tiny demo team
+
+# Optional: skill slugs to install with `openclaw recipes install my-first-team`
+requiredSkills: []
+
+team:
+  teamId: my-first-team
+
+agents:
+  - role: lead
+    name: Team Lead
+    tools:
+      profile: coding
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+
+  - role: worker
+    name: Worker
+    tools:
+      profile: coding
+      allow: ["group:fs", "group:web"]
+      deny: ["exec"]
+
+templates:
+  lead.soul: |
+    # SOUL.md
+
+    You are the lead for {{teamId}}.
+    Convert requests into tickets and assign work.
+
+  lead.agents: |
+    # AGENTS.md
+
+    Team directory: {{teamDir}}
+
+    Workflow:
+    - Intake: check `inbox/`
+    - Normalize: create tickets in `work/backlog/`
+    - Assign: write stubs in `work/assignments/`
+
+  worker.soul: |
+    # SOUL.md
+
+    You are a worker on {{teamId}}.
+
+  worker.agents: |
+    # AGENTS.md
+
+    Team directory: {{teamDir}}
+
+    How you work:
+    - Pick the lowest numbered ticket assigned to you.
+    - Move it to `work/in-progress/`.
+    - Do the work.
+    - When ready for QA, move it to `work/testing/` and assign Owner to `test`.
+    - After QA passes, move it to `work/done/` and write a short completion report.
+
+files:
+  - path: SOUL.md
+    template: soul
+    mode: createOnly
+  - path: AGENTS.md
+    template: agents
+    mode: createOnly
+
+# Default tools if an agent doesn’t override tools above
+tools:
+  profile: coding
+  allow: ["group:fs", "group:web"]
+  deny: ["exec"]
+---
+
+# My First Team
+
+This is a demo recipe.
+```
+
+## Step 2 — scaffold the team
+Important: team ids must end with `-team`.
+
+```bash
+openclaw recipes scaffold-team my-first-team --team-id my-first-team-team --apply-config
+```
+
+You should now have:
+- `~/.openclaw/workspace-my-first-team-team/` (team shared workspace)
+- `~/.openclaw/workspace-my-first-team-team/roles/lead/`
+- `~/.openclaw/workspace-my-first-team-team/roles/worker/`
+
+## Step 3 — dispatch a request
+```bash
+openclaw recipes dispatch \
+  --team-id my-first-team-team \
+  --request "Draft a README for the team" \
+  --owner worker
+```
+
+This will propose (or write, with `--yes`) three artifacts:
+- an inbox entry
+- a backlog ticket
+- an assignment stub
+
+## Step 4 — run the workflow
+Tickets move through lanes:
+- `work/backlog/` → `work/in-progress/` → `work/testing/` → `work/done/`
+
+- Move the ticket from `work/backlog/` → `work/in-progress/`
+- Do the work
+- When ready for QA:
+  - Move the ticket to `work/testing/`
+  - Set `Owner: test` and add **Verification steps** to the ticket
+- After verification:
+  - Move the ticket to `work/done/` and add a short completion report
+
+## Common mistakes
+- **Forgetting the `-team` suffix** on `--team-id` (required).
+- Using `deny: ["exec"]` on agents that need to run commands.
+- Not restarting the gateway after installing the plugin.
+
+## Next steps
+- Read `docs/RECIPE_FORMAT.md` for full frontmatter coverage.
+- Copy and modify a bundled recipe from `docs/BUNDLED_RECIPES.md`.