@clawcipes/recipes 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# Clawcipes (OpenClaw Recipes Plugin)
+
+<p align="center">
+  <img src="./clawcipes_cook.jpg" alt="Clawcipes logo" width="240" />
+</p>
+
+Clawcipes is an OpenClaw plugin that provides **CLI-first recipes** for scaffolding specialist agents and teams from Markdown.
+
+If you like durable workflows: Clawcipes is built around a **file-first team workspace** (inbox/backlog/in-progress/done) that plays nicely with git.
+
+## Quickstart
+### 1) Install
+#### Option A (preferred): install from npm
+Once published:
+
+```bash
+openclaw plugins install @clawcipes/recipes
+openclaw gateway restart
+openclaw plugins list
+```
+
+#### Option B: install from GitHub
+```bash
+git clone https://github.com/rjdjohnston/clawcipes.git ~/clawcipes
+openclaw plugins install --link ~/clawcipes
+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 \
+  --overwrite \
+  --apply-config
+```
+
+### 4) Dispatch a request into work artifacts
+```bash
+openclaw recipes dispatch \
+  --team-id development-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)
+- `openclaw recipes scaffold-team` (team)
+- `openclaw recipes install <idOrSlug> [--yes]` (workspace-local skill install)
+- `openclaw recipes dispatch ...` (request → inbox + ticket + assignment)
+
+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`)
+
+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`
+
+Reference:
+- Commands: `docs/COMMANDS.md`
+- Recipe format: `docs/RECIPE_FORMAT.md`
+- Bundled recipes: `docs/BUNDLED_RECIPES.md`
+- Team workflow: `docs/TEAM_WORKFLOW.md`
+- Clawcipes Kitchen (UI): `docs/CLAWCIPES_KITCHEN.md`
+
+(Also see: GitHub repo https://github.com/rjdjohnston/clawcipes)
+## Notes / principles
+- Workspace-local skills live in `~/.openclaw/workspace/skills` by default.
+- Team IDs end with `-team`; agent IDs are namespaced: `<teamId>-<role>`.
+- Recipe template rendering is intentionally simple: `{{var}}` replacement only.
+
+## Links
+- GitHub: https://github.com/rjdjohnston/clawcipes
+- 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)
+Clawcipes 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 → done)

package/docs/AGENTS_AND_SKILLS.md

@@ -0,0 +1,155 @@
+# Agents and skills (OpenClaw + Clawcipes)
+
+This doc explains the mental model: **what an agent is**, how **skills/tools** work, and how Clawcipes 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 Clawcipes, an agent is typically created by scaffolding a folder like:
+
+```
+~/.openclaw/workspace/agents/<agentId>/
+  SOUL.md
+  AGENTS.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).
+
+Clawcipes 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.
+
+## Installing skills (workspace-local)
+Clawcipes 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:
+- `~/.openclaw/workspace/skills/<skill-slug>` (by default)
+
+### 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
+Clawcipes currently does **not** implement a remove command.
+
+To remove a workspace-local skill:
+- delete the folder: `~/.openclaw/workspace/skills/<skill-slug>`
+- restart: `openclaw gateway restart`
+
+(We can add `openclaw recipes uninstall <slug>` later if you want it to be first-class.)
+
+## Teams: shared workspace + multiple agents
+A **team** recipe scaffolds:
+- a shared team folder under `teams/<teamId>/...`
+- multiple agents under `agents/<teamId>-<role>/...`
+
+The shared workspace is the source of truth for:
+- intake (`inbox/`)
+- work queue (`work/backlog`, `work/in-progress`, `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:
+- `~/.openclaw/workspace/agents/<agentId>/`
+
+Common files:
+- `SOUL.md` — the persona / operating style
+- `AGENTS.md` — operating instructions / workflow
+
+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`:
+
+```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`, Clawcipes 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
+
+Clawcipes 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 @@
+# Clawcipes Kitchen (UI)
+
+Clawcipes Kitchen is our UI for managing Clawcipes 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
+Clawcipes Kitchen is under active development.
+
+## Relationship to the plugin
+- The **Clawcipes plugin** is CLI-first and works without any UI.
+- Clawcipes 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/done)
+- Publishing workflow integration

package/docs/COMMANDS.md

@@ -0,0 +1,111 @@
+# 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>`
+Scaffold a team workspace + multiple agents from a **team** recipe.
+
+```bash
+openclaw recipes scaffold-team development-team \
+  --team-id development-team \
+  --overwrite \
+  --apply-config
+```
+
+Options:
+- `--team-id <teamId>` (required)
+  - **Must end with `-team`** (enforced)
+- `--overwrite`
+- `--apply-config`
+
+Creates a team directory with standard subfolders:
+- `teams/<teamId>/{shared,inbox,outbox,notes,work}`
+- `teams/<teamId>/work/{backlog,in-progress,done,assignments}`
+
+Also creates agent workspaces under:
+- `agents/<teamId>-<role>/...`
+
+## `install <idOrSlug> [--yes]`
+Install skills into the **workspace-local** skills directory.
+
+```bash
+openclaw recipes install local-places
+openclaw recipes install local-places --yes
+```
+
+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 <workspaceRoot> --dir skills install <slug>`
+- Confirmation-gated unless `--yes`.
+- In non-interactive mode (no TTY), requires `--yes`.
+
+## `dispatch`
+Convert a natural-language request into file-first execution artifacts.
+
+```bash
+openclaw recipes dispatch \
+  --team-id development-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` (default: `dev`)
+- `--yes` (skip review prompt)
+
+Creates (createOnly):
+- `teams/<teamId>/inbox/<timestamp>-<slug>.md`
+- `teams/<teamId>/work/backlog/<NNNN>-<slug>.md`
+- `teams/<teamId>/work/assignments/<NNNN>-assigned-<owner>.md`
+
+Ticket numbering:
+- Scans `work/backlog`, `work/in-progress`, `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,76 @@
+# 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 @clawcipes/recipes
+openclaw gateway restart
+openclaw plugins list
+```
+
+### Option B: install from GitHub
+```bash
+git clone https://github.com/rjdjohnston/clawcipes.git ~/clawcipes
+openclaw plugins install --link ~/clawcipes
+openclaw gateway restart
+openclaw plugins list
+```
+
+### Option B: already cloned
+```bash
+openclaw plugins install --link ~/clawcipes
+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 ~/clawcipes
+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 installs go into the workspace-local skills dir (default `~/.openclaw/workspace/skills`).