@jiggai/recipes 0.4.18 → 0.4.19

package/README.md

@@ -265,7 +265,10 @@ If you are new, read these in order:
 2. [Commands](docs/COMMANDS.md)
 3. [Team workflow](docs/TEAM_WORKFLOW.md)
 4. [Workflow runs](docs/WORKFLOW_RUNS_FILE_FIRST.md)
-5. [Outbound posting](docs/OUTBOUND_POSTING.md)
+5. [Workflow examples](docs/WORKFLOW_EXAMPLES.md)
+6. [Outbound posting](docs/OUTBOUND_POSTING.md)
+7. [Memory system](docs/MEMORY_SYSTEM.md)
+8. [Swarm Orchestrator](docs/SWARM_ORCHESTRATOR.md)
 
 If you are building recipes:
 

package/docs/BUNDLED_RECIPES.md

@@ -188,6 +188,9 @@ Inspect it first:
 openclaw recipes show swarm-orchestrator
 ```
 
+More:
+- [SWARM_ORCHESTRATOR.md](SWARM_ORCHESTRATOR.md)
+
 ---
 
 ## Best way to choose a recipe

package/docs/COMMANDS.md

@@ -302,8 +302,9 @@ Examples:
 So if you install the plugin and then say "the workflow exists but does not fully work," check the optional workflow dependencies next.
 
 More:
-- [WORKFLOW_RUNS_FILE_FIRST.md](WORKFLOW_RUNS_FILE_FIRST.md)
-- [OUTBOUND_POSTING.md](OUTBOUND_POSTING.md)
+- [WORKFLOW_RUNS_FILE_FIRST.md](WORKFLOW_RUNS_FILE_FIRST.md) — node kinds, triggers, runs, edges, runner/worker model, approvals
+- [WORKFLOW_EXAMPLES.md](WORKFLOW_EXAMPLES.md) — copy-paste workflow patterns
+- [OUTBOUND_POSTING.md](OUTBOUND_POSTING.md) — publishing/posting behavior and setup
 
 ---
 

package/docs/MEMORY_SYSTEM.md

@@ -0,0 +1,304 @@
+# Memory System
+
+This document explains the ClawRecipes memory system in practical terms, especially as it appears in the team editor.
+
+If you want the short version:
+- memory is **file-first**
+- not all memory is the same
+- private continuity, team coordination, team knowledge, and role memory should stay separate
+- the team editor should help you see and manage the right layer without mixing them up
+
+This doc builds on the canonical memory model doc:
+- [MEMORY_MODEL.md](MEMORY_MODEL.md)
+
+---
+
+## Why this exists
+
+Without a clear memory system, teams end up dumping everything everywhere:
+- private context leaks into shared files
+- ticket status gets mixed with durable knowledge
+- role-specific learnings get lost
+- nobody knows where to put anything
+
+ClawRecipes avoids that by being explicit about memory layers.
+
+---
+
+## The four memory layers
+
+ClawRecipes uses four memory layers:
+
+1. assistant continuity memory
+2. team coordination docs
+3. team knowledge memory
+4. role memory
+
+The canonical explanation lives here:
+- [MEMORY_MODEL.md](MEMORY_MODEL.md)
+
+This page is the easier operational guide.
+
+---
+
+## Layer 1: assistant continuity memory
+
+What it is:
+- the assistant’s own continuity
+- preferences
+- personal working context
+- long-running private context
+
+Typical files:
+- `SOUL.md`
+- `USER.md`
+- `memory/YYYY-MM-DD.md`
+- `MEMORY.md`
+
+Important rule:
+- this does **not** belong in the team workspace
+
+Use this for:
+- assistant continuity
+- private context
+- user-specific preferences
+
+Do not use it for:
+- shared team knowledge
+- team ticket history
+- shared operational docs
+
+---
+
+## Layer 2: team coordination docs
+
+What it is:
+- the team’s operating surface
+- plans, tickets, status, assignments, checklists
+
+Typical files:
+- `work/backlog/`
+- `work/in-progress/`
+- `work/testing/`
+- `work/done/`
+- `notes/plan.md`
+- `notes/status.md`
+- `TICKETS.md`
+- `AGENTS.md`
+
+Use this for:
+- what the team is doing right now
+- blockers
+- decisions attached to tickets
+- ongoing work coordination
+
+Do not use it for:
+- curated long-term knowledge base entries
+- private assistant memory
+
+---
+
+## Layer 3: team knowledge memory
+
+What it is:
+- shared durable knowledge for the whole team
+- facts worth keeping
+- canonical links
+- runbooks
+- known fixes
+- decisions worth reusing later
+
+Typical files:
+
+```text
+shared-context/memory/
+  team.jsonl
+  pinned.jsonl
+```
+
+Use this for:
+- reusable knowledge
+- facts the whole team should remember
+- high-signal decisions worth pinning
+
+This is the memory layer most closely associated with a memory tab in the team editor.
+
+---
+
+## Layer 4: role memory
+
+What it is:
+- continuity for one role inside the team
+- role-specific learnings and playbooks
+
+Typical files:
+
+```text
+roles/<role>/
+  MEMORY.md
+  memory/YYYY-MM-DD.md
+```
+
+Use this for:
+- role-specific learnings
+- role runbooks
+- role continuity that should not become global team knowledge yet
+
+Examples:
+- QA-specific release checks
+- dev-specific implementation gotchas
+- lead-specific prioritization habits
+
+---
+
+## Team editor angle
+
+From the team editor point of view, the memory system should feel like a set of clearly separated panels, not one giant dumping ground.
+
+A good team editor should help you understand:
+- what belongs in team memory vs role memory
+- what is operational status vs durable knowledge
+- what is pinned vs append-only
+- what should stay private and never move into team memory
+
+### The most useful things the team editor can surface
+
+#### Memory overview
+- short explanation of the memory layers
+- link to the canonical memory model doc
+
+#### Team memory
+- `shared-context/memory/team.jsonl`
+- `shared-context/memory/pinned.jsonl`
+- counts / recent entries / pinned items
+
+#### Coordination docs
+- `notes/status.md`
+- `notes/plan.md`
+- current ticket lanes
+
+#### Role memory
+- links into `roles/<role>/MEMORY.md`
+- links into role daily memory files
+
+#### Policy docs
+- `notes/memory-policy.md`
+- any team-specific memory conventions
+
+In other words:
+- the editor should help you navigate the memory system
+- the files remain the real source of truth
+
+---
+
+## What goes where?
+
+### Put it in team coordination docs when...
+- it is about current work
+- it is ticket-specific
+- it is a progress update
+- it is a blocker or immediate plan
+
+### Put it in team knowledge memory when...
+- it is reusable later
+- the whole team should know it
+- it is a known fix / canonical answer / stable reference
+
+### Put it in role memory when...
+- it mainly belongs to one role
+- it is useful continuity for that role
+- it is not yet broad enough to become team-wide knowledge
+
+### Keep it in assistant continuity memory when...
+- it is private context
+- it is user/assistant specific
+- it should not leak into the team workspace
+
+---
+
+## Pinned vs append-only memory
+
+### Append-only memory
+This is the stream of memory as things are learned.
+
+Examples:
+- `team.jsonl`
+- daily memory files
+- status logs
+
+### Pinned memory
+This is the smaller curated set of high-signal items worth keeping easy to find.
+
+Example:
+- `pinned.jsonl`
+
+Rule of thumb:
+- append everything useful first
+- pin only the things you expect to matter again later
+
+---
+
+## Suggested habits
+
+### After finishing work
+- update the ticket comments
+- append to `notes/status.md`
+- save artifacts to `shared-context/agent-outputs/`
+- if a reusable lesson emerged, write it to team memory
+- if it is especially important, pin it
+
+### During triage or lead review
+- move short-lived work chatter into tickets/status docs
+- move durable lessons into team knowledge memory
+- curate pinned memory so it stays high-signal
+
+### For role agents
+- keep role-specific continuity in role memory
+- escalate broadly useful knowledge into team memory
+
+---
+
+## Common mistakes
+
+### 1) Treating status logs like a knowledge base
+`notes/status.md` is for operational history, not your long-term memory system.
+
+### 2) Dumping private context into shared memory
+Private assistant continuity should stay private.
+
+### 3) Pinning too much
+If everything is pinned, nothing is pinned.
+
+### 4) Never promoting useful knowledge
+If good lessons stay buried in tickets forever, the team never really learns.
+
+### 5) Skipping role memory
+Role memory is useful because not every lesson belongs at the whole-team level.
+
+---
+
+## Simple example
+
+Imagine a team learns these three things:
+
+1. “Ticket 0042 is blocked waiting on API credentials.”
+2. “The fix for workflow-runner approval retries is to clear stale locks before requeue.”
+3. “QA should always capture screenshots for UI changes.”
+
+Where should they go?
+
+- #1 → ticket comments / `notes/status.md`
+- #2 → team knowledge memory (`team.jsonl`, maybe pin it)
+- #3 → role memory for QA, and maybe team memory too if it is now a team-wide rule
+
+---
+
+## How this connects to the canonical doc
+
+This page is the practical operating guide.
+
+The canonical model and boundaries remain here:
+- [MEMORY_MODEL.md](MEMORY_MODEL.md)
+
+If you want the philosophy and the exact layer definitions, read that doc.
+If you want to know how to use the memory system day-to-day, start here.

package/docs/SWARM_ORCHESTRATOR.md

@@ -0,0 +1,317 @@
+# Swarm Orchestrator
+
+This document explains what the **Swarm Orchestrator** is, when to use it, and how to work with it from the team editor.
+
+If you want the short version:
+- a normal team handles work through shared files and ticket lanes
+- a swarm orchestrator is for **parallel coding work** using **git worktrees + tmux sessions**
+- it is best when one lead wants to fan work out to multiple coding agents at once
+
+---
+
+## What it is
+
+The Swarm Orchestrator is a recipe/scaffold that creates an orchestration workspace for parallel coding work.
+
+Its job is to:
+- split work into focused tasks
+- spin up multiple coding agents in parallel
+- give each one its own branch/worktree/session
+- track what is active
+- help monitor and clean up those parallel tasks
+
+Think of it as a coordination layer for multi-agent coding, not as a replacement for the normal team workspace.
+
+---
+
+## When to use it
+
+Use Swarm Orchestrator when:
+- one ticket can be split into several parallel coding tasks
+- you want separate branches/worktrees for isolation
+- you want to monitor several coding sessions at once
+- you want a lead/orchestrator role to coordinate multiple implementation attempts
+
+Do **not** use it when:
+- the work is simple enough for one normal ticket/one agent
+- you do not want git worktrees
+- you do not want tmux sessions
+- the extra orchestration overhead is not worth it
+
+---
+
+## What it creates
+
+The bundled `swarm-orchestrator` recipe creates an orchestrator workspace with files like:
+
+```text
+.clawdbot/
+  CONVENTIONS.md
+  PROMPT_TEMPLATE.md
+  TEMPLATE.md
+  env.sh
+  spawn.sh
+  task.sh
+  check-agents.sh
+  cleanup.sh
+  active-tasks.json
+```
+
+These files are the operating surface for the orchestrator.
+
+Important ones:
+- `CONVENTIONS.md` — naming rules and defaults
+- `PROMPT_TEMPLATE.md` — the required base prompt for spawned coding agents
+- `TEMPLATE.md` — starter task/spec shape
+- `env.sh` — local environment values
+- `spawn.sh` / `task.sh` — start work
+- `check-agents.sh` — inspect current swarm sessions
+- `cleanup.sh` — safe cleanup helpers
+- `active-tasks.json` — lightweight task registry
+
+---
+
+## Core concepts
+
+### Worktree
+Each coding task gets its own git worktree.
+
+That means one repo can support multiple isolated task directories at the same time.
+
+### Branch
+Each task gets its own branch.
+
+That keeps parallel agent work separated and easier to review.
+
+### tmux session
+Each coding agent runs in its own tmux session.
+
+That means you can:
+- attach to it
+- watch it live
+- steer it
+- recover it if needed
+
+### Registry
+The orchestrator keeps a lightweight registry of active tasks in:
+
+```text
+.clawdbot/active-tasks.json
+```
+
+This is the quick answer to:
+- what is running?
+- on what branch?
+- in which worktree?
+- in which tmux session?
+
+---
+
+## Team editor angle
+
+From the team editor point of view, the Swarm Orchestrator is useful when you want a visible place to manage parallel implementation work.
+
+The team editor should help you:
+- see whether an orchestrator exists for the team
+- see the orchestrator workspace path
+- inspect active tasks / sessions / branches
+- know where env/config values live
+- know which files to edit for conventions and prompts
+
+A good mental model for the team editor is:
+- the team editor is the dashboard
+- the orchestrator workspace is the operating surface
+
+So if the editor shows a Swarm Orchestrator area, the most useful things it can surface are:
+- worktree root
+- base ref
+- active tasks
+- task ids
+- tmux session names
+- registry status
+- links to `.clawdbot/CONVENTIONS.md` and `.clawdbot/PROMPT_TEMPLATE.md`
+
+---
+
+## How to inspect the recipe
+
+```bash
+openclaw recipes show swarm-orchestrator
+```
+
+This is the fastest way to inspect what the bundled recipe currently scaffolds.
+
+---
+
+## Typical setup flow
+
+### 1) Scaffold the orchestrator
+
+The exact scaffold command depends on how you want to install it, but the first thing is to inspect the recipe and then scaffold it into a workspace.
+
+```bash
+openclaw recipes show swarm-orchestrator
+```
+
+If you are using it as a standalone workspace recipe, scaffold it like your other recipes.
+
+---
+
+### 2) Configure environment values
+
+The orchestrator relies on values in `.clawdbot/env.sh`.
+
+Common ones include:
+- `SWARM_REPO_DIR`
+- `SWARM_WORKTREE_ROOT`
+- `SWARM_BASE_REF`
+- optional agent-runner command settings
+
+Practical advice:
+- keep worktrees in a dedicated folder
+- keep that folder outside the repo
+- keep it outside the OpenClaw workspace if possible
+
+---
+
+### 3) Check prerequisites
+
+Common prerequisites include:
+- `git`
+- `tmux`
+- `jq`
+
+The orchestrator recipe/source docs also mention these directly.
+
+---
+
+## Starting work
+
+The orchestrator’s job is to start focused tasks.
+
+Typical pattern:
+- create a task spec
+- choose branch/worktree/session names
+- spawn the task
+- record/update the registry
+
+The scaffolded scripts are designed to help with that.
+
+Example commands from the orchestrator workspace:
+
+```bash
+./.clawdbot/task.sh start --task-id 0082 --spec "Implement workflow queue improvements"
+```
+
+Or directly:
+
+```bash
+./.clawdbot/spawn.sh feat-0082-a codex swarm-0082-a
+```
+
+Exact flags may vary with your local scaffold/version, so treat the local generated files as the source of truth.
+
+---
+
+## Monitoring work
+
+To inspect current orchestrated work:
+
+```bash
+./.clawdbot/check-agents.sh
+```
+
+And for tmux directly:
+
+```bash
+tmux ls
+tmux attach -t swarm-0082-a
+```
+
+Use the registry too:
+
+```bash
+cat ./.clawdbot/active-tasks.json
+```
+
+This gives you the fastest picture of:
+- active tasks
+- branch names
+- worktree paths
+- tmux sessions
+- rough task status
+
+---
+
+## Cleanup
+
+There is also a cleanup script in the scaffold.
+
+Typical use:
+
+```bash
+./.clawdbot/cleanup.sh
+```
+
+Important rule:
+- do **not** delete worktrees/branches casually
+- cleanup should stay conservative unless explicitly enabled
+
+That caution matters, because orchestrator cleanup can otherwise destroy in-progress work.
+
+---
+
+## Suggested workflow
+
+A practical orchestrator loop looks like this:
+
+1. identify a ticket worth parallelizing
+2. break it into 2–N focused tasks
+3. create one branch/worktree/session per task
+4. monitor progress via tmux + registry
+5. review outputs / PRs
+6. merge or discard branches intentionally
+7. clean up finished worktrees
+
+---
+
+## Common mistakes
+
+### 1) Using swarm for tiny work
+If one agent can do it cleanly, swarm is probably overkill.
+
+### 2) Not setting a dedicated worktree root
+That turns cleanup and inspection into a mess.
+
+### 3) Letting naming drift
+Use the conventions file. Otherwise you end up with branch/session chaos.
+
+### 4) Treating tmux as optional when debugging
+If agents are launched into tmux, tmux is the source of truth for what is actually happening live.
+
+### 5) Deleting worktrees too early
+Only clean up once branches/PRs/status are clearly done.
+
+---
+
+## How this should relate to the team editor
+
+The team editor should make orchestrator use easier by exposing:
+- whether the team has an orchestrator
+- the orchestrator workspace location
+- key env/config values
+- active tasks summary
+- links to conventions/prompt files
+- where to monitor/clean up
+
+This is the sweet spot:
+- editor for visibility and navigation
+- orchestrator workspace/scripts for execution
+
+---
+
+## Recommended related docs
+
+- [TEAM_WORKFLOW.md](TEAM_WORKFLOW.md)
+- [BUNDLED_RECIPES.md](BUNDLED_RECIPES.md)
+- [AGENTS_AND_SKILLS.md](AGENTS_AND_SKILLS.md)

package/docs/TEAM_WORKFLOW.md

@@ -199,6 +199,10 @@ Because it gives you:
 - easy automation
 - less dependency on one UI or one database
 
+Related:
+- [MEMORY_SYSTEM.md](MEMORY_SYSTEM.md)
+- [SWARM_ORCHESTRATOR.md](SWARM_ORCHESTRATOR.md)
+
 ---
 
 ## Recommended daily commands