@jiggai/recipes 0.4.17 → 0.4.18

package/docs/COMMANDS.md

@@ -1,351 +1,385 @@
-# Command reference
+# ClawRecipes command reference
 
-All commands live under:
+All commands are under:
 
 ```bash
 openclaw recipes <command>
 ```
 
-## `list`
-List available recipes (builtin + workspace).
+This page is organized by the jobs humans actually need to do.
+
+---
+
+## 1) Browse recipes
+
+### List all recipes
 
 ```bash
 openclaw recipes list
 ```
 
-Outputs JSON rows:
-- `id`, `name`, `kind`, `source`
-
-## `show <id>`
-Print the raw recipe markdown.
+### Show one recipe
 
 ```bash
 openclaw recipes show development-team
 ```
 
-## `status [id]`
-Check missing skills for a recipe (or all recipes).
+### Check recipe status / missing skills
 
 ```bash
 openclaw recipes status
 openclaw recipes status development-team
 ```
 
-## `scaffold <recipeId>`
-Scaffold a single agent workspace from an **agent** recipe.
+---
+
+## 2) Install recipes and skills
+
+### Install a marketplace recipe into your workspace
+
+```bash
+openclaw recipes install development-team
+openclaw recipes install clinic-team --overwrite
+```
+
+Optional:
+- `--registry-base <url>`
+- `--overwrite`
+
+Alias:
+
+```bash
+openclaw recipes install-recipe development-team
+```
+
+### Install a skill from ClawHub
 
 ```bash
-openclaw recipes scaffold project-manager --agent-id pm --name "Project Manager" --apply-config
+# global
+openclaw recipes install-skill agentchat --yes
+
+# scoped to one agent
+openclaw recipes install-skill agentchat --yes --agent-id dev
+
+# scoped to one team
+openclaw recipes install-skill agentchat --yes --team-id development-team
 ```
 
 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)
-- Cron: see Cron installation under scaffold-team.
+- `--yes`
+- `--global`
+- `--agent-id <id>`
+- `--team-id <id>`
 
-Also writes a workspace recipe file:
-- `~/.openclaw/workspace/recipes/<recipeId>.md`
+---
 
-## `scaffold-team <recipeId>`
+## 3) Scaffold agents and teams
 
-Scaffold a shared **team workspace** + multiple agents from a **team** recipe.
+### Scaffold a single agent
 
 ```bash
-openclaw recipes scaffold-team development-team \
-  --team-id development-team-team \
-  --overwrite \
+openclaw recipes scaffold project-manager \
+  --agent-id pm \
+  --name "Project Manager" \
   --apply-config
 ```
 
-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)
+Useful options:
+- `--agent-id <id>`
+- `--name <name>`
+- `--recipe-id <recipeId>`
+- `--auto-increment`
+- `--overwrite-recipe`
 - `--overwrite`
 - `--apply-config`
 
-Also writes a workspace recipe file:
-- `~/.openclaw/workspace/recipes/<recipeId>.md`
+What it writes:
+- `~/.openclaw/workspace-<agentId>/...`
+- workspace recipe file under `~/.openclaw/workspace/recipes/`
+
+### Scaffold a team
+
+```bash
+openclaw recipes scaffold-team development-team \
+  --team-id development-team \
+  --apply-config \
+  --overwrite
+```
 
-Creates a shared team workspace root:
+Useful options:
+- `--team-id <teamId>`
+- `--recipe-id <recipeId>`
+- `--auto-increment`
+- `--overwrite-recipe`
+- `--overwrite`
+- `--apply-config`
 
+What it writes:
 - `~/.openclaw/workspace-<teamId>/...`
+- role folders under `roles/`
+- ticket lanes under `work/`
+- workspace recipe file under `~/.openclaw/workspace/recipes/`
 
-Standard folders:
-- `inbox/`, `outbox/`, `shared/`, `notes/`
-- `work/{backlog,in-progress,testing,done,assignments}`
-- `roles/<role>/...` (role-specific recipe files)
+### Add a role to an existing team
 
-Also creates agent config entries under `agents.list[]` (when `--apply-config`), with agent ids:
-- `<teamId>-<role>`
+```bash
+openclaw recipes add-role \
+  --team-id development-team \
+  --role workflow-runner \
+  --recipe workflow-runner-addon \
+  --apply-config
+```
 
-### Cron installation
-If a recipe declares `cronJobs`, scaffold and scaffold-team 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`
+Useful options:
+- `--team-id <teamId>`
+- `--role <role>`
+- `--recipe <recipeId>`
+- `--agent-id <agentId>`
+- `--apply-config`
+- `--overwrite`
+- `--no-cron`
 
-Applies to both `scaffold` and `scaffold-team` when the recipe declares `cronJobs`.
+---
 
-## `install-skill <idOrSlug> [--yes]`
-Install skills from ClawHub (confirmation-gated).
+## 4) Work the file-first ticket flow
 
-Default: **global** into `~/.openclaw/skills`.
+The normal lane flow is:
 
-```bash
-# Global (shared across all agents)
-openclaw recipes install-skill agentchat --yes
+```text
+backlog → in-progress → testing → done
+```
 
-# Agent-scoped (into workspace-<agentId>/skills)
-openclaw recipes install-skill agentchat --yes --agent-id dev
+### Turn a request into a ticket
 
-# Team-scoped (into workspace-<teamId>/skills)
-openclaw recipes install-skill agentchat --yes --team-id development-team-team
+```bash
+openclaw recipes dispatch \
+  --team-id development-team \
+  --owner lead \
+  --request "Add a customer-support team recipe"
 ```
 
 Options:
-- `--yes` — skip confirmation
-- `--global` — install into global skills (default when no scope flags)
-- `--agent-id <id>` — install into agent workspace
-- `--team-id <id>` — install into team workspace
-
-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 ...`. Confirmation-gated unless `--yes`. In non-interactive mode (no TTY), requires `--yes`.
+- `--team-id <teamId>`
+- `--request <text>`
+- `--owner dev|devops|lead|test`
+- `--yes`
 
-## `install <slug>`
-Install a marketplace recipe into your workspace recipes dir (by slug).
+### List tickets
 
 ```bash
-openclaw recipes install development-team
-openclaw recipes install development-team --overwrite
+openclaw recipes tickets --team-id development-team
+openclaw recipes tickets --team-id development-team --json
 ```
 
-Options:
-- `--registry-base <url>` — Marketplace API base URL (default: `https://clawkitchen.ai`)
-- `--overwrite` — overwrite existing recipe file
+### Move a ticket between lanes
 
-Use `install-recipe` as an alias for this command.
+```bash
+openclaw recipes move-ticket --team-id development-team --ticket 0007 --to in-progress
+openclaw recipes move-ticket --team-id development-team --ticket 0007 --to testing
+openclaw recipes move-ticket --team-id development-team --ticket 0007 --to done --completed
+```
 
-## `bind`
-Add/update a multi-agent routing binding (writes `bindings[]` in `~/.openclaw/openclaw.json`).
+Options:
+- `--team-id <teamId>`
+- `--ticket <ticket>`
+- `--to backlog|in-progress|testing|done`
+- `--completed`
+- `--yes`
 
-Examples:
+### Assign a ticket
 
 ```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
+openclaw recipes assign --team-id development-team --ticket 0007 --owner dev
+openclaw recipes assign --team-id development-team --ticket 0007 --owner lead
 ```
 
-Notes:
-- `peer.kind` must be one of: `dm|group|channel`.
-- Peer-specific bindings are inserted first (more specific wins).
+Options:
+- `--team-id <teamId>`
+- `--ticket <ticket>`
+- `--owner dev|devops|lead|test`
+- `--overwrite`
+- `--yes`
 
-## `unbind`
-Remove routing binding(s) from OpenClaw config (`bindings[]`).
+### Take a ticket
 
-Examples:
+Shortcut for assign + move to in-progress.
 
 ```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
+openclaw recipes take --team-id development-team --ticket 0007 --owner dev
 ```
 
-## `bindings`
-Print the current `bindings[]` from OpenClaw config.
+### Handoff to testing
 
 ```bash
-openclaw recipes bindings
+openclaw recipes handoff --team-id development-team --ticket 0007
+openclaw recipes handoff --team-id development-team --ticket 0007 --tester test
 ```
 
-## `migrate-team`
-Migrate a legacy team scaffold into the new `workspace-<teamId>` layout.
+### Complete a ticket
 
 ```bash
-openclaw recipes migrate-team --team-id development-team-team --dry-run
-openclaw recipes migrate-team --team-id development-team-team --mode move
+openclaw recipes complete --team-id development-team --ticket 0007
 ```
 
-Options:
-- `--dry-run`
-- `--mode move|copy`
-- `--overwrite` (merge into existing destination)
-
-## `remove-team`
-Safe uninstall: remove a scaffolded team workspace, agents from config, and stamped cron jobs.
+### Clean up stale assignment stubs for done work
 
 ```bash
-openclaw recipes remove-team --team-id development-team-team --plan --json
-openclaw recipes remove-team --team-id development-team-team --yes
+openclaw recipes cleanup-closed-assignments --team-id development-team
+openclaw recipes cleanup-closed-assignments --team-id development-team --ticket 0050 0064
 ```
 
-Options:
-- `--team-id <teamId>` (required)
-- `--plan` — print plan and exit without applying
-- `--json` — output JSON
-- `--yes` — skip confirmation (apply destructive changes)
-- `--include-ambiguous` — also remove cron jobs that only loosely match the team (dangerous)
+---
 
-Notes:
-- Confirmation-gated by default. Use `--yes` to apply without prompting.
-- Cron cleanup removes only cron jobs stamped with `recipes.teamId=<teamId>`.
-- Restart required after removal: `openclaw gateway restart`
+## 5) Workflows
 
-## `dispatch`
-Convert a natural-language request into file-first execution artifacts (inbox + backlog ticket + assignment stubs).
+Use these when you are running file-first workflows from `shared-context/workflows/`.
+
+### See workflow command help
 
 ```bash
-openclaw recipes dispatch \
-  --team-id development-team-team \
-  --request "Add a customer-support team recipe" \
-  --owner lead
+openclaw recipes workflows --help
 ```
 
-Options:
-- `--team-id <teamId>` (required)
-- `--request <text>` (optional; prompts in TTY)
-- `--owner dev|devops|lead|test` (default: `dev`)
-- `--yes` (skip review prompt)
+### Run one workflow manually
 
-Creates:
-- `workspace-<teamId>/inbox/<timestamp>-<slug>.md`
-- `workspace-<teamId>/work/backlog/<NNNN>-<slug>.md`
-- `workspace-<teamId>/work/assignments/<NNNN>-assigned-<owner>.md`
+```bash
+openclaw recipes workflows run \
+  --team-id development-team \
+  --workflow-file marketing.workflow.json
+```
 
-Ticket numbering:
-- Scans `work/backlog`, `work/in-progress`, `work/testing`, `work/done` and uses max+1.
+### Runner commands
 
-Review-before-write:
-- Prints a JSON plan and asks for confirmation unless `--yes`.
+```bash
+openclaw recipes workflows runner-once --team-id development-team
+
+openclaw recipes workflows runner-tick \
+  --team-id development-team \
+  --concurrency 2 \
+  --lease-seconds 120
+```
 
-## Ticket workflow commands
+### Worker commands
 
-The following commands manage the file-first ticket flow (`work/backlog` → `in-progress` → `testing` → `done`).
+```bash
+openclaw recipes workflows worker-tick \
+  --team-id development-team \
+  --agent-id development-team-lead \
+  --limit 10
+```
 
-### `tickets`
-List tickets for a team across the standard workflow stages.
+### Approval commands
 
 ```bash
-openclaw recipes tickets --team-id <teamId>
-openclaw recipes tickets --team-id <teamId> --json
+openclaw recipes workflows approve \
+  --team-id development-team \
+  --run-id <runId> \
+  --approved true
+
+openclaw recipes workflows approve \
+  --team-id development-team \
+  --run-id <runId> \
+  --approved false \
+  --note "Rewrite the hook"
+
+openclaw recipes workflows resume \
+  --team-id development-team \
+  --run-id <runId>
+
+openclaw recipes workflows poll-approvals \
+  --team-id development-team \
+  --limit 20
 ```
 
-## `cleanup-workspaces`
-List (dry-run, default) or delete (with `--yes`) temporary test/scaffold team workspaces under your OpenClaw home directory.
+### Important workflow note
 
-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
+After installing ClawRecipes, workflows may still need optional pieces turned on.
 
 Examples:
-```bash
-# Dry-run (default): list what would be deleted
-openclaw recipes cleanup-workspaces
-
-# Actually delete eligible workspaces
-openclaw recipes cleanup-workspaces --yes
+- LLM workflows may require the built-in `llm-task` plugin to be enabled
+- publishing workflows may require `outbound.post` config or a local posting patch to be reapplied
 
-# Custom prefixes (repeatable)
-openclaw recipes cleanup-workspaces --prefix smoke- --prefix qa- --yes
+So if you install the plugin and then say "the workflow exists but does not fully work," check the optional workflow dependencies next.
 
-# JSON output
-openclaw recipes cleanup-workspaces --json
-```
+More:
+- [WORKFLOW_RUNS_FILE_FIRST.md](WORKFLOW_RUNS_FILE_FIRST.md)
+- [OUTBOUND_POSTING.md](OUTBOUND_POSTING.md)
 
-### `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
-```
+## 6) Bindings
 
-Stages:
-- `backlog` → `Status: queued`
-- `in-progress` → `Status: in-progress`
-- `testing` → `Status: testing`
-- `done` → `Status: done` (optional `Completed:` timestamp)
+Bindings route messages/traffic to the right agent.
 
-### `assign`
-Assign a ticket to an owner (updates `Owner:` and creates an assignment stub).
+### Show bindings
 
 ```bash
-openclaw recipes assign --team-id <teamId> --ticket 0007 --owner dev
-openclaw recipes assign --team-id <teamId> --ticket 0007 --owner lead
+openclaw recipes bindings
 ```
 
-Owners (current): `dev|devops|lead|test`.
-
-### `take`
-Shortcut: assign + move to in-progress.
+### Add a binding
 
 ```bash
-openclaw recipes take --team-id <teamId> --ticket 0007 --owner dev
+openclaw recipes bind \
+  --agent-id dev \
+  --channel telegram \
+  --peer-kind dm \
+  --peer-id 6477250615
 ```
 
-### `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.
+### Remove a binding
 
 ```bash
-openclaw recipes handoff --team-id <teamId> --ticket 0007
-openclaw recipes handoff --team-id <teamId> --ticket 0007 --tester test
+openclaw recipes unbind \
+  --agent-id dev \
+  --channel telegram \
+  --peer-kind dm \
+  --peer-id 6477250615
 ```
 
-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.
+---
+
+## 7) Migrate / remove / clean up
 
-### `complete`
-Shortcut: move to done + ensure `Status: done` + add `Completed:` timestamp. No confirmation prompt.
+### Migrate a legacy team layout
 
 ```bash
-openclaw recipes complete --team-id <teamId> --ticket 0007
+openclaw recipes migrate-team --team-id development-team --dry-run
+openclaw recipes migrate-team --team-id development-team --mode move
 ```
 
-## `workflows <subcommand>`
-
-Workflow runner utilities (file-first runs, runner/worker model).
+### Remove a team safely
 
 ```bash
-openclaw recipes workflows --help
+openclaw recipes remove-team --team-id development-team --plan --json
+openclaw recipes remove-team --team-id development-team --yes
 ```
 
-Common commands:
+### Clean up temporary workspaces
 
 ```bash
-# Run a workflow once (manual trigger)
-openclaw recipes workflows run --team-id <teamId> --workflow-file <file.workflow.json>
-
-# Runner (scheduler)
-openclaw recipes workflows runner-once --team-id <teamId>
-openclaw recipes workflows runner-tick --team-id <teamId>
+# dry-run
+openclaw recipes cleanup-workspaces
 
-# Worker (executor) — pull-based per-agent queue
-openclaw recipes workflows worker-tick --team-id <teamId> --agent-id <agentId>
+# delete allowed temp prefixes
+openclaw recipes cleanup-workspaces --prefix smoke- --prefix qa- --yes
 
-# Approval gating
-openclaw recipes workflows approve --team-id <teamId> --run-id <runId> --decision approve
-openclaw recipes workflows resume --team-id <teamId> --run-id <runId>
-openclaw recipes workflows poll-approvals --team-id <teamId>
+# json output
+openclaw recipes cleanup-workspaces --json
 ```
 
-See: `docs/WORKFLOW_RUNS_FILE_FIRST.md`
+---
+
+## Fastest useful command set
+
+If you only want the high-value commands:
+
+```bash
+openclaw recipes list
+openclaw recipes scaffold-team development-team --team-id development-team --apply-config
+openclaw recipes dispatch --team-id development-team --owner lead --request "Do a thing"
+openclaw recipes tickets --team-id development-team
+openclaw recipes take --team-id development-team --ticket 0001 --owner dev
+openclaw recipes handoff --team-id development-team --ticket 0001
+openclaw recipes complete --team-id development-team --ticket 0001
+```