@clawcipes/recipes 0.1.0

package/docs/RECIPE_FORMAT.md

@@ -0,0 +1,107 @@
+# 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 `.`, Clawcipes prefixes it with `<role>.`.
+
+## 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,55 @@
+# Team workflow (file-first)
+
+Clawcipes’ differentiator is the **shared team workspace** + a simple, durable, file-first workflow.
+
+## Team workspace structure
+When you scaffold a team:
+
+```
+teams/<teamId>/
+  inbox/
+  outbox/
+  shared/
+  notes/
+  work/
+    backlog/
+    in-progress/
+    done/
+    assignments/
+  TICKETS.md
+  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/`.
+- Do work; write artifacts into `shared/` or agent workspaces.
+
+4) **Complete**
+- Move ticket to `work/done/`.
+- Add a `*.DONE.md` report next to it.
+
+## 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,142 @@
+# 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 Clawcipes 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/`.
+    - Complete it and write a report in `work/done/`.
+
+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/teams/my-first-team-team/`
+- `~/.openclaw/workspace/agents/my-first-team-team-lead/`
+- `~/.openclaw/workspace/agents/my-first-team-team-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
+- Move the ticket from `work/backlog/` → `work/in-progress/`
+- Do the work
+- Move the ticket to `work/done/` and add a `*.DONE.md` 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`.