@jiggai/recipes 0.2.11

package/README.md

@@ -0,0 +1,142 @@
+# ClawRecipes (OpenClaw Recipes Plugin)
+
+<p align="center">
+  <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.
+
+If you like durable workflows: ClawRecipes is built around a **file-first team workspace** (inbox/backlog/in-progress/testing/done) that plays nicely with git.
+
+## Quickstart
+### 1) Install
+#### Option A (preferred): install from npm
+Once published:
+
+```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
+```
+
+### 2) List available recipes
+```bash
+openclaw recipes list
+```
+
+### 3) Scaffold a team
+```bash
+openclaw recipes scaffold-team development-team \
+  --team-id development-team-team \
+  --overwrite \
+  --apply-config
+```
+
+### 4) Dispatch a request into work artifacts
+```bash
+openclaw recipes dispatch \
+  --team-id development-team-team \
+  --request "Add a new recipe for a customer-support team" \
+  --owner lead
+```
+
+## 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 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)
+- `openclaw recipes tickets|move-ticket|assign|take|handoff|complete` (file-first ticket workflow)
+- `openclaw recipes cleanup-workspaces` (safe cleanup of temporary test/scaffold workspaces)
+
+For full details, see `docs/COMMANDS.md`.
+
+## Configuration
+The plugin supports these config keys (with defaults):
+- `workspaceRecipesDir` (default: `recipes`)
+- `workspaceAgentsDir` (default: `agents`)
+- `workspaceSkillsDir` (default: `skills`)
+- `workspaceTeamsDir` (default: `teams`)
+- `autoInstallMissingSkills` (default: `false`)
+- `confirmAutoInstall` (default: `true`)
+- `cronInstallation` (default: `prompt`; values: `off|prompt|on`)
+
+Config schema is defined in `openclaw.plugin.json`.
+
+## Documentation
+Start here:
+- Installation: `docs/INSTALLATION.md`
+- Agents + skills: `docs/AGENTS_AND_SKILLS.md`
+- Tutorial (create a recipe): `docs/TUTORIAL_CREATE_RECIPE.md`
+
+## Development
+### Unit tests (vitest)
+Run:
+- `npm test`
+
+### Scaffold smoke test (regression)
+A lightweight smoke check validates scaffold-team output contains the required testing workflow docs (ticket 0004).
+
+Run:
+- `npm run test:smoke` (or `npm run scaffold:smoke`)
+
+Notes:
+- Creates a temporary `workspace-smoke-<timestamp>-team` under `~/.openclaw/` and then deletes it.
+- Exits non-zero on mismatch.
+
+Reference:
+- Commands: `docs/COMMANDS.md`
+- Recipe format: `docs/RECIPE_FORMAT.md`
+- Bundled recipes: `docs/BUNDLED_RECIPES.md`
+- Team workflow: `docs/TEAM_WORKFLOW.md`
+- ClawRecipes Kitchen (UI): `docs/CLAWCIPES_KITCHEN.md`
+
+(Also see: GitHub repo https://github.com/JIGGAI/ClawRecipes)
+## Notes / principles
+- Workspaces:
+  - Standalone agents: `~/.openclaw/workspace-<agentId>/`
+  - Teams: `~/.openclaw/workspace-<teamId>/` with `roles/<role>/...`
+- Skills:
+  - Global (shared): `~/.openclaw/skills/<skill>`
+  - Scoped (agent/team): `~/.openclaw/workspace-*/skills/<skill>`
+- Team IDs end with `-team`; agent IDs are namespaced: `<teamId>-<role>`.
+- Recipe template rendering is intentionally simple: `{{var}}` replacement only.
+
+## Removing (uninstalling) a scaffolded team
+ClawRecipes includes a safe uninstall command:
+
+```bash
+openclaw recipes remove-team --team-id <teamId> --plan --json
+openclaw recipes remove-team --team-id <teamId> --yes
+openclaw gateway restart
+```
+
+Notes:
+- The command is confirmation-gated by default (use `--yes` to apply).
+- Cron cleanup is conservative: it removes only cron jobs that are explicitly **stamped** with `recipes.teamId=<teamId>`.
+- If you need a manual fallback, you can still delete `~/.openclaw/workspace-<teamId>` and remove `<teamId>-*` agents from `agents.list[]` in `~/.openclaw/openclaw.json`.
+
+## 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)
+ClawRecipes is meant to be *installed* and then used to build **agents + teams**.
+
+Most users should focus on:
+- authoring recipes in their OpenClaw workspace (`<workspace>/recipes/*.md`)
+- scaffolding teams (`openclaw recipes scaffold-team ...`)
+- running the file-first workflow (dispatch → backlog → in-progress → testing → done)

package/docs/AGENTS_AND_SKILLS.md

@@ -0,0 +1,232 @@
+# Agents and skills (OpenClaw + ClawRecipes)
+
+This doc explains the mental model: **what an agent is**, how **skills/tools** work, and how ClawRecipes helps you build agents + teams.
+
+## What is an agent?
+In OpenClaw, an **agent** is a configured assistant persona with:
+- a **workspace folder** (where it reads/writes files)
+- optional **identity** (name, avatar, emoji, tone)
+- a **tool policy** (what tools it is allowed to use)
+- a **model** configuration (defaults come from OpenClaw)
+
+In ClawRecipes, a **standalone** agent recipe scaffolds a dedicated workspace like:
+
+```
+~/.openclaw/workspace-<agentId>/
+  SOUL.md
+  AGENTS.md
+  TOOLS.md
+  ...other recipe files...
+```
+
+### Why separate agents?
+- Separation of concerns (research vs writing vs devops)
+- Cleaner prompts/personas
+- Safer tool permissions (e.g., only DevOps gets automation)
+- Clear ownership of outputs (each agent writes to its own workspace)
+
+## What is a skill?
+A **skill** is a packaged integration or capability (e.g. Gmail, Calendar, Places search, Twitter/X tooling).
+
+Skills can provide:
+- tools/actions (e.g., `gog gmail ...`, `local-places ...`)
+- configuration schemas / env vars
+- helper scripts or CLIs
+
+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.
+
+## How to add/update tool access (allow list)
+There are two common approaches.
+
+### Option A (recommended): update the recipe, then re-apply config
+1) Edit the recipe markdown (either a workspace recipe or your own copy of a bundled recipe) and change `tools.allow` / `tools.deny`.
+
+2) Re-run scaffold with `--apply-config`:
+
+Team:
+```bash
+openclaw recipes scaffold-team <recipeId> --team-id <teamId> --overwrite --apply-config
+openclaw gateway restart
+```
+
+Individual agent:
+```bash
+openclaw recipes scaffold <recipeId> --agent-id <agentId> --overwrite --apply-config
+openclaw gateway restart
+```
+
+### Option B: edit OpenClaw config directly
+1) Edit:
+- `~/.openclaw/openclaw.json`
+
+2) Find the matching agent under `agents.list[]` and edit:
+- `tools.allow`
+- `tools.deny`
+
+3) Restart:
+```bash
+openclaw gateway restart
+```
+
+> Tip: if you later re-run scaffold with `--apply-config`, the recipe’s tool policy may overwrite your manual edits. If you want a change to stick, encode it in the recipe.
+
+## Installing skills (workspace-local)
+ClawRecipes favors **workspace-local** installs so each OpenClaw workspace is self-contained.
+
+### Install a skill slug
+```bash
+openclaw recipes install <skill-slug>
+# or non-interactive:
+openclaw recipes install <skill-slug> --yes
+```
+
+This runs ClawHub under the hood and installs into the **current OpenClaw workspace** skills dir:
+- `<workspace>/skills/<skill-slug>`
+
+Examples:
+- standalone agent workspace: `~/.openclaw/workspace-<agentId>/skills/<skill-slug>`
+- team workspace: `~/.openclaw/workspace-<teamId>/skills/<skill-slug>`
+
+> Note: in the new workspace policy, standalone agents live in `~/.openclaw/workspace-<agentId>` and teams live in `~/.openclaw/workspace-<teamId>`. Skill install targeting is still being refined during the experimental phase.
+
+### Install the skills required by a recipe
+If a recipe declares skills in `requiredSkills` or `optionalSkills`:
+
+```bash
+openclaw recipes install <recipe-id>
+```
+
+That installs the recipe’s declared skills.
+
+### Removing a skill
+ClawRecipes currently does **not** implement a remove command.
+
+To remove a workspace-local skill:
+- delete the folder: `<workspace>/skills/<skill-slug>`
+- restart: `openclaw gateway restart`
+
+(We can add `openclaw recipes uninstall <slug>` later if you want it to be first-class.)
+
+## Removing (uninstalling) a scaffolded team
+ClawRecipes includes a safe uninstall command:
+
+```bash
+openclaw recipes remove-team --team-id <teamId> --plan --json
+openclaw recipes remove-team --team-id <teamId> --yes
+openclaw gateway restart
+```
+
+Notes:
+- Cron cleanup is conservative: it removes only cron jobs explicitly stamped with `recipes.teamId=<teamId>`.
+- You can still do it manually by deleting `~/.openclaw/workspace-<teamId>` and removing `<teamId>-*` entries from `agents.list[]` in `~/.openclaw/openclaw.json`.
+
+## Teams: shared workspace + multiple agents
+A **team** recipe scaffolds a **shared workspace root** plus role folders:
+
+```
+~/.openclaw/workspace-<teamId>/
+  TEAM.md
+  inbox/
+  outbox/
+  shared/
+  notes/
+  work/
+    backlog/
+    in-progress/
+    testing/
+    done/
+    assignments/
+  roles/
+    <role>/
+      ...role-specific recipe files...
+```
+
+Each role agent is a separate OpenClaw agent id (`<teamId>-<role>`), but they share the same workspace root (`workspace-<teamId>`) so collaboration is file-based.
+
+The shared workspace is the source of truth for:
+- intake (`inbox/`)
+- work queue (`work/backlog`, `work/in-progress`, `work/testing`, `work/done`)
+- assignments (`work/assignments`)
+- deliverables (`outbox/`)
+
+## Updating agents after you scaffold them
+Once an agent exists, there are **two layers** you can update:
+
+### 1) The agent’s files (workspace)
+Agents are just folders under:
+- standalone: `~/.openclaw/workspace-<agentId>/`
+- team roles: `~/.openclaw/workspace-<teamId>/roles/<role>/`
+
+Common files:
+- `SOUL.md` — the persona / operating style
+- `AGENTS.md` — operating instructions / workflow
+- `TOOLS.md` — agent-local notes (paths, conventions, env quirks)
+- `STATUS.md` — current focus / next actions
+- `NOTES.md` — scratchpad
+
+To change behavior, edit these files and then just use the agent again.
+
+If the agent was created from a recipe, re-running scaffold with `--overwrite` will overwrite recipe-managed files:
+
+```bash
+openclaw recipes scaffold <recipeId> --agent-id <agentId> --overwrite
+```
+
+For teams, you typically re-run `scaffold-team` (role files live under `roles/<role>/`):
+
+```bash
+openclaw recipes scaffold-team <recipeId> --team-id <teamId> --overwrite
+```
+
+### 2) The agent’s OpenClaw config (tool permissions, identity, model)
+When you scaffold with `--apply-config`, ClawRecipes writes the agent entry into OpenClaw config:
+- `~/.openclaw/openclaw.json` → `agents.list[]`
+
+Re-run scaffold/scaffold-team with `--apply-config` any time you want the recipe’s tool policy (allow/deny) to be re-applied.
+
+```bash
+openclaw recipes scaffold-team <recipeId> --team-id <teamId> --apply-config
+openclaw gateway restart
+```
+
+## Where to find agent config in the OpenClaw UI
+OpenClaw exposes agent configuration in its UI (labels/paths depend on your build), typically under something like:
+- **Settings → Agents**
+
+From there you can:
+- select an agent
+- view/edit its identity
+- review tool permissions
+- confirm which workspace it uses
+
+If you prefer files, the source-of-truth config file is:
+- `~/.openclaw/openclaw.json`
+
+## How to create your own agents/teams
+You have three main options:
+
+1) Use a bundled recipe (fast start)
+- `openclaw recipes scaffold-team development-team --team-id my-dev-team-team --apply-config`
+
+2) Write your own recipe in your workspace
+- Create: `~/.openclaw/workspace/recipes/my-team.md`
+- Then: `openclaw recipes scaffold-team my-team --team-id my-team-team --apply-config`
+
+3) Copy a bundled recipe and modify it
+- Use `openclaw recipes show <id>` to view it
+- Copy into your workspace recipes dir and edit
+
+Next: read `docs/TUTORIAL_CREATE_RECIPE.md` for a step-by-step guide.

package/docs/BUNDLED_RECIPES.md

@@ -0,0 +1,208 @@
+# Bundled recipes
+
+ClawRecipes ships with a few recipes in `recipes/default/`.
+
+You can:
+- list them: `openclaw recipes list`
+- inspect them: `openclaw recipes show <id>`
+
+Below is a guided explanation of what each bundled recipe does.
+
+## 1) `project-manager` (agent)
+**Kind:** agent
+
+**Use when:** you want a lightweight agent that keeps plans tidy and maintains a cadence.
+
+Scaffold:
+```bash
+openclaw recipes scaffold project-manager --agent-id pm --name "Project Manager" --apply-config
+```
+
+What it writes:
+- `agents/pm/SOUL.md`
+- `agents/pm/AGENTS.md`
+
+Default tool policy (recipe-defined):
+- allows: `group:fs`, `group:web`, plus `cron` and `message`
+- denies: `exec`
+
+## 2) `social-team` (team)
+**Kind:** team
+
+**Use when:** you want a multi-role social pipeline: lead + research + writer + editor.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team social-team --team-id social-team-team --apply-config
+```
+
+What it creates:
+- `teams/social-team-team/` shared workspace
+- agents:
+  - `agents/social-team-team-lead/`
+  - `agents/social-team-team-research/`
+  - `agents/social-team-team-writer/`
+  - `agents/social-team-team-editor/`
+
+Notes:
+- Default `tools` in the recipe deny `exec` (safer by default).
+
+## 3) `development-team` (team)
+**Kind:** team
+
+**Use when:** you want a small engineering team with a file-first ticket queue.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team development-team --team-id development-team-team --apply-config
+```
+
+What it creates:
+- `teams/development-team-team/` shared workspace
+- agents:
+  - `agents/development-team-team-lead/`
+  - `agents/development-team-team-dev/`
+  - `agents/development-team-team-devops/`
+
+Special features:
+- A strict ticket workflow documented in the lead’s `AGENTS.md`.
+- Recommended ticket naming: `0001-...md`, `0002-...md`, etc.
+- Tool policies intended for real work:
+  - lead: includes runtime + automation
+  - dev: includes runtime
+  - devops: includes runtime + automation
+
+## 4) `research-team` (team)
+**Kind:** team
+
+**Use when:** you need repeatable, citations-first research output.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team research-team --team-id research-team-team --apply-config
+```
+
+What it creates:
+- shared team workspace with conventional research folders:
+  - `work/sources/`, `work/notes/`, `work/briefs/`
+- agents:
+  - lead (dispatch + quality bar)
+  - researcher (web sourcing + notes)
+  - fact-checker (verification)
+  - summarizer (brief writing)
+
+Default tool policy:
+- allows web access + file operations
+- denies `exec` (safe-by-default)
+
+## 5) `writing-team` (team)
+**Kind:** team
+
+**Use when:** you want a writing pipeline from brief → outline → draft → edit.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team writing-team --team-id writing-team-team --apply-config
+```
+
+What it creates:
+- shared team workspace with writing pipeline folders:
+  - `work/briefs/`, `work/outlines/`, `work/drafts/`, `work/edited/`
+- agents:
+  - lead
+  - outliner
+  - writer
+  - editor
+
+Default tool policy:
+- allows web access + file operations
+- denies `exec` (safe-by-default)
+
+## 6) `customer-support-team` (team)
+**Kind:** team
+
+**Use when:** you want a repeatable support workflow: triage → resolution → KB.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team customer-support-team --team-id customer-support-team-team --apply-config
+```
+
+What it creates:
+- shared workspace conventions:
+  - `work/cases/`, `work/replies/`, `work/kb/`
+- agents:
+  - lead, triage, resolver, kb-writer
+
+Default tool policy:
+- allows web access + file operations
+- denies `exec` (safe-by-default)
+
+## 7) `product-team` (team)
+**Kind:** team
+
+**Use when:** you want a PRD → design → build → QA delivery loop.
+
+Scaffold:
+```bash
+openclaw recipes scaffold-team product-team --team-id product-team-team --apply-config
+```
+
+Notes:
+- The `engineer` role allows `group:runtime` and does **not** deny `exec` so it can run local tooling.
+
+## 8) `researcher` (agent)
+**Kind:** agent
+
+**Use when:** you want a single, citations-first research agent.
+
+Scaffold:
+```bash
+openclaw recipes scaffold researcher --agent-id researcher --apply-config
+```
+
+Default tool policy:
+- allows web access + file operations
+- denies `exec`
+
+## 9) `editor` (agent)
+**Kind:** agent
+
+**Use when:** you want a single editing agent.
+
+Scaffold:
+```bash
+openclaw recipes scaffold editor --agent-id editor --apply-config
+```
+
+Default tool policy:
+- allows web access + file operations
+- denies `exec`
+
+## 10) `developer` (agent)
+**Kind:** agent
+
+**Use when:** you want a single developer agent with runtime tooling.
+
+Scaffold:
+```bash
+openclaw recipes scaffold developer --agent-id dev --apply-config
+```
+
+Default tool policy:
+- allows `group:runtime`
+- does not deny `exec`
+
+## Copying and modifying bundled recipes
+A good workflow is:
+1) Inspect:
+```bash
+openclaw recipes show development-team > /tmp/development-team.md
+```
+
+2) Copy into your workspace recipes folder:
+```bash
+cp /tmp/development-team.md ~/.openclaw/workspace/recipes/my-dev-team.md
+```
+
+3) Edit the new recipe file and scaffold it.

package/docs/CLAWCIPES_KITCHEN.md

@@ -0,0 +1,27 @@
+# ClawRecipes Kitchen (UI)
+
+ClawRecipes Kitchen is our UI for managing ClawRecipes workflows.
+
+## What it’s for
+- Activity feed (high-level semantic events)
+- Weekly scheduled-task view
+- Global search across workspace + memory/docs + tasks
+- Agent chat room
+- Goals system (file-based source of truth)
+- Approvals inbox + routing (e.g., Telegram)
+
+## Status
+ClawRecipes Kitchen is under active development.
+
+## Relationship to the plugin
+- The **ClawRecipes plugin** is CLI-first and works without any UI.
+- ClawRecipes Kitchen is an optional UI companion for:
+  - visibility (activity/search)
+  - approvals
+  - human review of plans and changes
+
+## Roadmap (high level)
+- Approvals UI (approve/deny + audit trail)
+- Recipe browser and scaffold flows
+- Team dashboards (backlog/in-progress/testing/done)
+- Publishing workflow integration