
orchestrate
Multi-agent orchestration for lionagi: plan DAG workflows, author playbooks, run multi-play shows with quality gates.
- GitHub stars
- 412
Install
/plugin install orchestrate@lionagiRun it inside Claude Code after adding the marketplace with /plugin marketplace add ohdearquant/lionagi.
Contents
Discovered from sourceSkills 12
Debug
Systematic approach to difficult debugging. Research → Orchestrate → Escalate.
Activation Triggers
- Stuck on error after 2-3 failed fix attempts
- Unfamiliar library or dependency version
- Tempted to "try things randomly"
- Complex multi-system interactions
- Error messages that don't match documentation
Anti-Patterns
- Random flailing: Trying fixes without understanding the problem
- Editing generated files: Modifying auto-generated output instead of fixing the source
- Shallow fixes: Adding workarounds without understanding root cause
- Silent struggling: Not asking for help when clearly stuck
- Cheating through: Disabling features or tests instead of fixing them
Workflow Summary
| Phase | Action | Gate |
|---|---|---|
| 1. Research | Check prior runs, search codebase, spawn researcher agent | 2-3 focused queries before any fix attempt |
| 2. Orchestrate | Parallel diagnostic agents via fanout.submit, or a focused agent via agent.submit | Agent must produce actionable insight |
| 3. Escalate | Generate consultation request with full evidence | Must demonstrate exhaustive research first |
| 4. Document | Write fix to ./notes/debug-log.md | Only after resolution |
See research-protocol.md for detailed methodology, agent selection table, phase-by-phase MCP calls, and escalation template.
Key Principles
- Research before action: Never try fixes without understanding the problem
- Be specific: Vague queries yield vague answers
- Document attempts: Track what was tried and what happened
- Ask early: Better to ask for help than waste time flailing
- Store the fix: Future sessions will thank present you
Relevant Source Files
These are the CLI-side entry points; read them if you're working inside a lionagi checkout. A plugin install has no access to them — it only sees the MCP server.
lionhub/src/lionhub/serve/cli/agent.py—li agent, the CLI counterpart ofagent.submitlionhub/src/lionhub/serve/cli/orchestrate/fanout.py—li o fanout, the CLI counterpart offanout.submitlionhub/src/lionhub/orchestration/runs.py— run persistence at~/.lionagi/runs/, also readable throughjob.status/job.output
Running a Fanout
Use fanout.submit when every worker can receive the same task independently. Use flow when
one worker needs another's output or the run should discover reactive follow-up work.
Required call sequence
Ask for the catalog first, in its own call, and confirm fanout.submit is available:
mcp__plugin_orchestrate_lion__request(help=true)
Then fetch the verb's full current schema and fingerprint:
mcp__plugin_orchestrate_lion__request(help="fanout.submit")
Do not combine help and ops. Copy the returned fingerprint beside args, never inside it.
Worked example
Run four independent analyses and synthesize them into one recommendation:
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "fanout.submit",
"args": {
"query": ["claude"],
"prompt": "Identify the main risks in migrating a Python service from threads to asyncio.",
"num_workers": 4,
"with_synthesis": true,
"synthesis_prompt": "Merge the analyses into a prioritized migration checklist."
},
"schema_fingerprint": "<fingerprint from help=\"fanout.submit\">"}
])
The response returns a run_id immediately while the run continues in the background. It is
not the synthesized answer. Observe and retrieve it with separate calls:
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "job.status", "args": {"run_id": "<run_id>"}}
])
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "job.output", "args": {"run_id": "<run_id>"}}
])
job.list finds recent runs, and job.kill stops one by run_id.
Capacity and boundaries
num_workerscaps the initial independent assignments; the planner may produce fewer.fanout.submitis a fixed fanout. Its current schema has noreactive,max_ops, ordry_runargument, so do not pass those names.- For reactive discovery, use
flow.submit. Its spawn capacity ismax_ops - initial assignment countwhenmax_opsis nonzero. A plan that fillsmax_opshas no capacity left for follow-ups; reserve headroom and verify the initial plan withdry_run: true. - Ops in one request run in order. A failed op returns
ok=falsewithout stopping its siblings, so inspect every op result.
Checkout-local alternative
Inside a lionagi checkout with li on PATH:
li o fanout claude "Identify the main risks in migrating a Python service from threads to asyncio." \
-n 4 --with-synthesis --synthesis-prompt "Produce a prioritized migration checklist."
Running a Dependency DAG
Use flow.submit when tasks have dependency edges or workers should be able to discover
follow-up work during execution. Use fanout for a fixed set of independent perspectives.
Required call sequence
Ask for the catalog first, in its own call, and confirm flow.submit is available:
mcp__plugin_orchestrate_lion__request(help=true)
For a prompt-driven flow with no playbook, fetch the exact schema and fingerprint:
mcp__plugin_orchestrate_lion__request(help="flow.submit")
If args names a playbook, instead ask with the exact same spelling because the schema and
fingerprint vary by playbook:
mcp__plugin_orchestrate_lion__request(help={"verb": "flow.submit", "playbook": "feature"})
Never combine help and ops. Put schema_fingerprint beside args, not inside it.
Worked example
First plan only. The prompt limits the initial DAG to four assignments while max_ops: 6
reserves capacity for up to two reactive follow-ups:
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "flow.submit",
"args": {
"query": ["claude"],
"prompt": "Create at most four initial assignments to analyze an API migration, propose a plan, and independently verify it. Preserve remaining capacity for follow-up work discovered by the workers.",
"max_ops": 6,
"reactive": "all",
"with_synthesis": true,
"dry_run": true
},
"schema_fingerprint": "<fingerprint from help=\"flow.submit\">"}
])
The dry run is a background job. Read its returned run_id with job.status and
job.output. Confirm the planned assignment count leaves headroom, then resubmit the same op
without dry_run:
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "flow.submit",
"args": {
"query": ["claude"],
"prompt": "Create at most four initial assignments to analyze an API migration, propose a plan, and independently verify it. Preserve remaining capacity for follow-up work discovered by the workers.",
"max_ops": 6,
"reactive": "all",
"with_synthesis": true
},
"schema_fingerprint": "<fingerprint from help=\"flow.submit\">"}
])
The second response returns a new run_id, not the final answer. Poll it and retrieve output:
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "job.status", "args": {"run_id": "<run_id>"}}
])
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "job.output", "args": {"run_id": "<run_id>"}}
])
job.list finds recent runs, and job.kill stops one by run_id.
Reactive budget
For a nonzero max_ops, reactive spawn capacity is max_ops - initial assignment count.
The planner and reactive spawns share that one budget; there is no separate reservation
parameter. If the dry-run plan already contains max_ops assignments, follow-ups have zero
capacity. Tighten the requested initial plan or raise max_ops before execution.
With max_ops: 0, the CLI leaves the initial plan uncapped and applies its separate default
reactive-spawn ceiling. Prefer an explicit total when cost needs to be predictable.
Multiple outer MCP ops run in order, but a failure returns ok=false without stopping its
siblings. Check every op's ok field.
Checkout-local alternative
Inside a lionagi checkout with li on PATH:
li o flow claude "Create at most four initial assignments to analyze an API migration." \
--max-ops 6 --reactive all --with-synthesis --dry-run
orchestrate
Plan and execute multi-agent workflows through lionagi's orchestration MCP server. The
plugin ships one MCP tool, mcp__plugin_orchestrate_lion__request, which dispatches
namespaced verbs behind a single ops array — not a CLI, not one tool per verb.
Start here, every session
mcp__plugin_orchestrate_lion__request(help=true)
Call this once, in its own call (never combined with ops), before writing any spawn call.
It returns the verb catalog, each verb's required parameters, and either its
schema_fingerprint or a marker that the fingerprint varies by playbook (see
reference.md). Never guess a parameter name — this call and targeted help are the source
of truth.
When to use which verb
| Situation | Verb |
|---|---|
| Single task, one agent | agent.submit |
| Same prompt to N independent workers | fanout.submit |
| Staged pipeline with dependencies | flow.submit |
| Pre-saved parametric workflow | play.submit |
| Check on a run already submitted | job.status, job.wait, job.output |
If all subtasks are independent (no output feeds another), use fanout.submit.
If any subtask depends on the output of another, use flow.submit.
play.submit loads a saved prompt and defaults, then uses the same planner and executor as
flow.submit.
Every *.submit call spawns a detached background run and returns a run id right
away — there is no blocking call that returns a finished answer. Read the result back with
job.status, job.wait, or job.output.
Quick start
# Catalog + fingerprints, once per session
mcp__plugin_orchestrate_lion__request(help=true)
# Single agent
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "agent.submit", "args": {"query": ["claude"], "prompt": "Write unit tests for auth.py"},
"schema_fingerprint": "<from help>"}
])
# Fan out 4 parallel workers + synthesize
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "fanout.submit",
"args": {"query": ["claude"], "prompt": "Review this codebase for security issues", "num_workers": 4, "with_synthesis": true},
"schema_fingerprint": "<from help>"}
])
# DAG flow — dry-run first, then commit
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "flow.submit",
"args": {"query": ["claude"], "prompt": "Audit auth, implement fixes, verify with tests", "dry_run": true},
"schema_fingerprint": "<from help>"}
])
# ... inspect the plan, then resend without dry_run ...
# Run a saved playbook
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "play.submit", "args": {"playbook": "feature", "prompt": "Add JWT middleware"},
"schema_fingerprint": "<from help={'verb': 'play.submit', 'playbook': 'feature'}>"}
])
# Check a run
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "job.wait", "args": {"run_ids": ["<run-id>"], "max_wait": 60}}
])
Key principles
help=truein its own call, before writing a spawn call — never combinehelpandopsin one call; the server refuses it.schema_fingerprintrides as a sibling ofargs, never inside it — every*.submitverb requires it, fetched fromhelp.- Named profiles are installation-specific — call
profile.listbefore passingagent, or pass a model through the verb's positionalqueryargument where supported. - Critic assignments depend on producers — a critic is an ordinary
TaskAssignment, not a special control node. Put it after every output it reviews. - Every assignment gets a separate branch — repeated roles do not share conversation memory. Pass results through declared dependencies and artifacts.
- Artifact paths are supplied by the engine — name outputs clearly and use the exact
upstream directories injected into downstream assignment context; do not guess
../paths. - Use
depends_ononly for real data dependencies — independent assignments leave it empty and run concurrently. - Reserve reactive capacity —
max_opsis shared by the initial plan and follow-up spawns; a plan that fills it leaves no room for reactive work. dry_runis a text preview — it does not build a run graph.show_graphwrites a graph artifact only after an executing flow finishes.- The catalog is the authority, not this bundle —
reference.mddocuments the verbs these skills call, which is a subset of what the server offers; and the shipped server resolves the latest lionagi release, so a verb you found by reading a checkout may not be there yet.help=truesettles both questions.
Companion references
For detailed documentation, read these companion files in this skill directory:
- reference.md — the MCP tool's parameter shapes for the verbs these
skills call, the
schema_fingerprintprotocol, and the secondaryliCLI flag tables - dag-planning.md —
TaskAssignmentdata model, dependency planning, branch and artifact handoff, reactive budgets - workflows.md — standard workflow patterns (parallel exploration, staged pipeline, long-running work, playbooks, visualization)
- teams-and-tracking.md — team coordination patterns, invocation tracking, scheduling — and which of these are CLI-only today
Source code
For someone working inside a lionagi checkout — informational, not part of the MCP surface:
| Component | Path |
|---|---|
| MCP server + verb catalog | lionhub/src/lionhub/serve/mcp/server.py, lionhub/src/lionhub/serve/mcp/verbs.py, lionhub/src/lionhub/serve/mcp/dispatch.py |
| CLI entrypoint | lionhub/src/lionhub/serve/cli/main.py |
Flow engine (TaskAssignment DAG) | lionhub/src/lionhub/serve/cli/orchestrate/flow.py |
| Fanout engine | lionhub/src/lionhub/serve/cli/orchestrate/fanout.py |
| Argparse definitions | lionhub/src/lionhub/serve/cli/orchestrate/__init__.py |
| Agent CLI | lionhub/src/lionhub/serve/cli/agent.py |
| Teams | lionhub/src/lionhub/serve/cli/team.py |
| Invocations | lionhub/src/lionhub/serve/cli/invoke.py |
| Scheduler engine | lionhub/src/lionhub/orchestration/scheduler/engine.py |
Running a Saved Playbook
Use play.submit for a playbook that is already installed on the MCP server's
machine. Use the playbook skill instead when the file itself needs authoring or editing.
Required call sequence
-
Ask for the catalog in its own call and confirm
play.submitis available:mcp__plugin_orchestrate_lion__request(help=true) -
Ask for the schema with the exact playbook name. A playbook's declared arguments change the schema, so the catalog marks this fingerprint as varying by
playbook:mcp__plugin_orchestrate_lion__request(help={"verb": "play.submit", "playbook": "minimal"}) -
Copy that reply's
schema_fingerprintinto the op as a sibling ofargs:mcp__plugin_orchestrate_lion__request(ops=[ {"op": "play.submit", "args": {"playbook": "minimal", "prompt": "Explain monads with one example."}, "schema_fingerprint": "<fingerprint from the qualified help call>"} ])
Never put schema_fingerprint inside args. It is not read there, so the server refuses the
op as stale. Do not combine help and ops in one call; the server refuses that shape too.
Worked example
This example uses a saved playbook at ~/.lionagi/playbooks/minimal.playbook.yaml. If it is
not already present, create it first:
name: minimal
model: claude
prompt: |
Explain the supplied topic in plain language, with one concrete example.
Run the qualified help and submit calls above, then read the returned run_id:
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "job.status", "args": {"run_id": "<run_id>"}}
])
Repeat job.status until the run is terminal, then retrieve its console tail and artifact list:
mcp__plugin_orchestrate_lion__request(ops=[
{"op": "job.output", "args": {"run_id": "<run_id>"}}
])
The submit response is only a run id, not the playbook's result. job.list finds recent runs;
job.kill stops one by run_id.
Arguments and planning
- Read the qualified help schema for every custom playbook argument. Pass each declared
argument directly inside the op's
args; do not invent another nesting layer. - Set
dry_run: trueinsideargsto plan without executing workers. The dry run is still a background job, so inspect it throughjob.statusandjob.output. - If calling
flow.submitwith aplaybookinstead, use the same qualified-help rule with{"verb": "flow.submit", "playbook": "<same name>"}. - Multiple ops run in order, but one op returning
ok=falsedoes not stop its siblings. Check every op'sokfield instead of trusting the top-level response alone.
Checkout-local alternative
Inside a lionagi checkout with li on PATH:
li play minimal "Explain monads with one example."
Use li play minimal --help to see the playbook's declared flags.
Authoring Lionagi Playbooks
A playbook is a .playbook.yaml file that defines a reusable, parametric agent
workflow. Install it in ~/.lionagi/playbooks/ on the machine the MCP server runs
on — that filesystem step is the same whichever interface runs the playbook.
To run it, call the mcp__plugin_orchestrate_lion__request tool with play.submit. Ask for
the fingerprint first, naming the playbook — play.submit's schema depends on which playbook
you name, because a playbook's own declared arguments are resolved into it:
{"help": {"verb": "play.submit", "playbook": "hello"}}
{"ops": [{"op": "play.submit", "args": {"playbook": "hello", "prompt": "what is a monad?"}, "schema_fingerprint": "<from the help call above>"}]}
The fingerprint is a sibling of args, never a key inside it. Omit it and the op is
refused with stale_schema and no run starts; nest it inside args and it is not read, so
the same refusal repeats and the failure reads as idempotent.
If you're working inside a lionagi checkout, the CLI equivalent is
li play <name> "<prompt>", which expands to li o flow -p <name> "<prompt>".
Minimum Viable Playbook
name: hello
description: Greet and answer a question.
model: claude-code/sonnet-4-6
prompt: |
You are a patient teacher. Explain the following topic in plain language,
with one concrete example.
Run it with play.submit:
{"ops": [{"op": "play.submit", "args": {"playbook": "hello", "prompt": "what is a monad?"}, "schema_fingerprint": "<from help={\"verb\": \"play.submit\", \"playbook\": \"hello\"}>"}]}
Inside a lionagi checkout: li play hello "what is a monad?"
The positional text is appended to the prompt with a blank line because the
template contains no {input} placeholder. That is the only behaviour difference
from a template that declares {input} explicitly.
Authoring Checklist
- Filename:
<name>.playbook.yaml - Location:
~/.lionagi/playbooks/ -
name:equals the filename stem — nothing validates the two against each other, and the CLI resolves by filename, so a mismatch is silent rather than an error -
description:is one clear sentence - Choose routing deliberately:
model:andagent:are optional; when both are omitted, flow uses its default orchestrator configuration. Ifagent:is set, verify that profile exists on the machine running the MCP server -
prompt:references only declaredargskeys and optional{input} - Every
argsentry declarestype,default, andhelp. A suppliedtypeis validated; omitting these fields yieldsstr, null, and a generated help line respectively - No dashed keys inside
args: -
team_modeandteam_attachare not both set -
workersis 1–32 if set;max_opsis 0–50 if set - If reactive follow-ups are enabled with a nonzero
max_ops, leave room below the cap; the initial plan and spawned assignments share the same budget - Dry-run check:
play.submitwithdry_run: trueplans without executing (callhelp=truefirst to confirm the argument name for your published server version) - Help check (lionagi checkout only):
li play <name> --helpalways lists fields fromargs:;argument-hintcontrols the usage line and can define fallback flags when noargs:block exists. Over MCP, qualified playbook help resolves the custom arguments
Companion Files
| File | Contents |
|---|---|
field-reference.md | Complete field table, args schema, template interpolation rules, team semantics, reserved names, pitfalls, source code reference |
examples.md | Three annotated example playbooks (minimal, audit, pr-review) plus the examples directory index |
patterns.md | Orchestration patterns and advanced composition strategies |
PR review procedure
A reusable rubric for reviewing a pull request. Works as an orchestrated
flow (via the fanout.submit or flow.submit MCP verbs, or li o fanout /
li o flow from a lionagi checkout) or for a solo reviewer.
When to use
Any time you need a structured PR review — OSS contribution evaluation, internal code review, security sign-off, release gate.
Workflow Phases
| Phase | Action |
|---|---|
| 0. Fetch context | gh pr view + gh pr diff → save to _context/ |
| 1. Discovery | Parallel specialists from closed set (correctness, security, architecture, tests, perf) |
| 2. Discussion | Optional — only if dimensions cross-pollinate |
| 3. Critic synthesis | Reads all findings → critic_final/final_synthesis.md |
| 4. Post comment | ONE consolidated comment per verbosity tier |
Verdict options
APPROVE | APPROVE-WITH-FIXES | REJECT
Verbosity tiers for posting
| Verbosity | Content | Safe for |
|---|---|---|
| none | don't post, synthesis stays local | any |
| brief | ≤10 lines: verdict + top MUST-FIX only | OSS |
| substantive | MUST-FIX + SHOULD-FIX with file:line; omit blind-spots | internal repos |
| full | complete synthesis including blind spots + coverage | private repos only |
Ground rules
- Cite line numbers against committed HEAD of the PR branch.
- Don't invent requirements — only flag if absence is a bug.
- If runtime context is needed that isn't in the diff, say so.
- Graceful degradation — note any tool failures in synthesis.
Related skills
security-review— threat-model rubric for the security dimensionreview— general correctness and quality rubric
See specialist-guide.md for specialist dimensions, severity rubric, synthesis format, MCP and CLI examples, and source code reference.
Code review procedure
A general-purpose review rubric for any code change. Use as the "correctness" specialist dimension of a multi-perspective review, or as a standalone checklist when reviewing a diff without a specialization.
Scope
Review ONLY the assigned diff. Cross-module concerns go to architecture; security-sensitive code goes to security-review.
Checklist summary (9 sections)
- Correctness — logic, control flow, off-by-one, error handling, invariants, concurrency, numeric
- API contract — backward compatibility, type annotations, error types, return value shape
- Tests — coverage of new paths, edge cases, mock fidelity, flaky risk
- Readability & maintainability — names, function length, nesting, comments, dead code
- Consistency — naming convention, error handling pattern, import ordering, abstraction level
- Docs & changelog — public API changes, behavioral changes, new config options
- Dependencies — necessity, maintenance, license, version constraints, lockfile
- Performance (light-touch) — obvious O(n²) regressions, hot-path allocations, N+1 queries
- Over/under-engineering — premature abstraction, speculative flexibility, too-simple cases
See checklist.md for the full detailed checklist with all sub-items.
Output format
Findings table per finding:
| Severity | Location | Issue | Suggested fix | Confidence |
|---|---|---|---|---|
| MEDIUM | src/module.py:87 | Off-by-one in range(len(xs)) | Use enumerate(xs) | High |
Verdict line at top: APPROVE | APPROVE-WITH-FIXES | REQUEST CHANGES.
Cite file:line for every finding.
Severity calibration
CRITICAL— will break production on mergeHIGH— correctness bug affecting real use casesMEDIUM— edge case bug, significant maintainability issueLOW— style, naming, minor refactorINFO— future consideration, not blocking
Ground rules
- Describe the bug, propose a fix.
- Don't invent requirements.
- Rank severity honestly.
- Flag assumptions you can't verify from the diff.
- Review against committed HEAD of the PR branch.
Security review procedure
A focused rubric for security review of a code change. Designed as the "security" specialist dimension of a multi-perspective PR review, but applies equally to a standalone audit.
Scope
Review ONLY your assigned diff (or module). Cross-module concerns go to the architecture specialist; correctness bugs without security impact go to correctness.
Checklist summary (10 sections)
- Authentication & authorization — endpoint auth checks, session tokens, RBAC, fail-closed, multi-tenant
- Input validation — type/range/length/encoding, parameterization, regex anchoring, structured data parsers
- Data exposure — error messages, logs, response fields, timing/cache leaks
- Crypto & secrets — hardcoded keys, safe defaults, weak primitives,
randomvssecrets, password hashing - Injection — SQL, shell, LDAP, template, HTML/XSS
- File / path handling — path containment, zip-slip, temp files, symlinks
- Supply chain — typosquatting, pinned versions, endpoint validation
- Deserialization & parsers — pickle, yaml.load, eval, exec, XXE
- Race conditions / TOCTOU — atomic file operations, lock scope
- Denial of service — unbounded loops on user input, rate limiting
See threat-model.md for full per-section detail and CWE mapping.
Severity calibration
CRITICAL— exploitable now, no special conditions: auth bypass, RCE, full data exposureHIGH— data exposure / auth gap requiring specific conditionsMEDIUM— mis-scoped tokens, weak validation, missing rate limitLOW— defense-in-depth hardeningINFO— notes for future consideration
Rule of thumb: CRITICAL vs HIGH — user action required to exploit? No = CRITICAL, chained = HIGH. HIGH vs MEDIUM — exploitable at attacker's expected access level? Yes = HIGH, needs escalation = MEDIUM.
Output format
| Severity | Location | Description | Suggested fix | Confidence | Runtime-context caveats |
|---|---|---|---|---|---|
| HIGH | file.py:112 | Path not containment-checked | Canonicalize, enforce containment, and use race-resistant access | High | Symlink and TOCTOU handling depends on the later file operation |
Verdict at top: APPROVE | REQUEST CHANGES | REJECT.
Cite file:line. Reference CWE where clear (CWE-22 path traversal, CWE-89 SQLi).
Ground rules
- Don't invent requirements.
- Flag runtime context you need but can't see.
- Be honest about confidence.
- Review against committed HEAD of the PR branch.
show
Orchestrate a complex goal as a sequence of gated plays. Each play is one run of a saved playbook, fired through the plugin's MCP server and executed in its own git worktree. The show coordinates: plan → fire → gate → merge → adapt → repeat.
Firing and observing plays go through the mcp__plugin_orchestrate_lion__request
tool this plugin ships (see procedure.md for the exact calls).
Everything about git — worktrees, branches, merges — is plain git and always
runs as Bash; there is no MCP verb for it and none is needed. If you are
working inside a lionagi checkout with li on PATH, li play and li agent
fire the same work; li wait blocks until a run reaches a terminal state, the
way repeated job.wait calls do; and li monitor, li runs and li kill
observe and stop it. Treat the CLI as a local convenience, not the primary path.
Shows vs flows — pick the right tool
| Dimension | flow.submit | show (this skill) |
|---|---|---|
| Execution | One dependency DAG | Multiple gated playbook runs |
| Unit of work | Planned assignment | Full playbook run (play.submit) |
| Branching | Single DAG | Each play gets its own worktree + branch |
| Human gate | Optional critic node | Between every play |
| Replanning | Worker-triggered reactive spawn requests | After every play based on verdict |
| Studio surface | Fleet | /api/shows endpoints; Fleet has no dedicated show page |
Use a show when: the goal requires multiple independent bodies of work, each needing its own branch and quality gate, with a plan that adapts based on intermediate results.
Use a flow when: one dependency-aware run can plan and execute the work as a DAG.
The 8-step procedure
- Plan — Write
_show.md(goal, plays, deps). Create the integration branch offmain. - Pick — Select the next play:
pendingstatus, alldepends_onplays aremerged. - Worktree —
git worktree add -b show/<topic>/<play>off the integration branch. - Fire — Call
play.submitfor the playbook; record the returnedrun_id. - Gate — Call
agent.submitwith the acceptance criteria; write_verdict.json. - Decide —
gate_passed=true→ merge; attempt 1 fail → redo; attempt 2 fail → escalate. - Adapt — Update
_show.mddecisions; adjust downstream_intent.mdif outputs changed. - Final gate — When all plays are terminal, run show-level gate; open PR if passed.
For the complete procedure with the exact MCP calls, see procedure.md.
Common mistakes
❌ Creating a show for a task one flow can finish — overkill, use flow.submit
❌ Not checking each op's `ok` in the reply — a partial batch can carry a failed op silently
❌ Calling help and ops in the same request — the server refuses that; ask help first, separately
❌ Treating one bounded job.wait call as completion — repeat until all_terminal is true
❌ Using git merge without --no-ff — loses play boundary in git history
❌ Skipping gate on attempt 2 — gate is mandatory before escalate decision
❌ Firing plays before integration branch exists — plays have nowhere to merge
❌ Touching _ABORT after all plays have launched — it only blocks new launches; use job.kill for running ones
❌ Keeping play worktrees after merge — they accumulate; remove after merge
❌ Not updating _show.md decisions after each play — that file is the readable record, so a stale one misleads everyone after you
Companion files
- data-model.md —
shows/playstable schema, status enums, reading a show from Studio - procedure.md — full 8-step procedure with the MCP calls, workspace layout,
_show.mdformat - gate-protocol.md — gate agents, verdict JSON, decision logic, abort/resume
Source code reference
| File | Purpose |
|---|---|
lionagi/state/schema.sql (CREATE TABLE shows, CREATE TABLE plays) | shows and plays table DDL |
lionagi/studio/services/shows.py | List, detail, import, SSE watcher, and the /api/shows routes |
lionagi/studio/registry.py | Registers that service with the app |
lionagi/studio/config.py | LIONAGI_SHOWS_ROOT and the root it falls back to |
apps/studio/frontend/src/components/shows/PlayDag.tsx | DAG visualization component; present in the tree, imported by nothing |
lionhub/src/lionhub/serve/mcp/server.py, lionhub/src/lionhub/serve/mcp/verbs.py | MCP verb registry — play.submit, job.* |
Summarize (Mid-Session)
Capture context, learnings, and progress without ending the session. Write a checkpoint, then continue.
When to Use
- Significant milestone reached but more work ahead
- Switching to a different topic within the same session
- Context getting close to its limit — checkpoint before compaction
- After completing a multi-step task, before starting the next
- Patterns or decisions have emerged that should be recorded
Not for session-ending summaries — use a full session summary for that.
Proactive Capture Triggers
Fire a capture immediately when any of these occur:
| Trigger | Action |
|---|---|
| Decision made | Record decision + rationale + alternatives considered |
| Pattern discovered | Note the pattern with "when to use" conditions |
| Significant work completed | Capture what was done + outcome |
| Problem solved | Record approach + what worked / what didn't |
| Session winding down | Offer to run a full session summary or auto-capture key points |
| Topic switch | Quick checkpoint before context shifts |
Session wind-down signals: "thanks", "that's it", "done for now", long pause after significant work, context switch to unrelated topic, time indicators ("gotta go", "wrapping up").
What's Worth Capturing
Always: architectural decisions, technology choices with rationale, bug root causes + fixes, performance optimizations, security considerations, integration patterns.
When significant: refactoring approaches, test strategies, debugging techniques, file organization decisions, naming conventions.
Skip: routine edits, typo fixes, standard boilerplate, obvious patterns already documented.
Key Principles
- Fast > thorough: This is a checkpoint, not a dissertation. Keep it brief enough to preserve momentum.
- File-first: Write to
./notes/checkpoints/so checkpoints survive context resets. - Continue after: This skill does NOT end the session.
- Compound: Multiple checkpoints per session is fine — they build a trail.
- Searchable: Use clear prefixes (CHECKPOINT, PATTERN, DECISION, LESSON) for future grep.
- Silent capture: Don't interrupt flow. Capture at natural breaks, not mid-thought.
Anti-Patterns
- Writing a full session summary mid-session (use a full session summary)
- Spending longer on the checkpoint than the work needs
- Only commenting in-line without writing a retrievable file
- Generic summaries without specifics ("worked on stuff")
- Over-capturing: not every line of code matters
See checkpoint-format.md for detailed checkpoint template, memory type distinction, decision/pattern/lesson capture templates, a delegated-capture example through the plugin's MCP server, and the quality guide.
Relevant Source Files
lionhub/src/lionhub/orchestration/runs.py— run persistence at~/.lionagi/runs/{run_id}/lionhub/src/lionhub/orchestration/console.py— structured logging conventions used in CLI sessionslionhub/src/lionhub/serve/mcp/server.py,lionhub/src/lionhub/serve/mcp/verbs.py—agent.submit/job.output, the MCP path for delegating a capture to a sub-agent and reading back its saved artifactslionhub/src/lionhub/serve/cli/agent.py—li agent, the checkout-local equivalent; it persists runs without a flag
TDD Workflow
Orchestrate test-driven development: Red → Green → Refactor.
Activation Triggers
- "TDD", "test-driven", "test first", "red green refactor"
- Bug fix where proving the bug first is valuable
- Feature with clear acceptance criteria
- "write the test before implementing"
The Cycle
| Phase | Action | Gate |
|---|---|---|
| RED | Write failing test expressing desired behavior | Run it — MUST fail. If it passes, it tests nothing new. |
| GREEN | Write minimum code to make the test pass | Run it — MUST pass. No over-engineering. |
| REFACTOR | Clean up while staying green | Run ALL tests — MUST pass. Never refactor with failures. |
Run commands
# lionagi Python
scripts/ci.sh test-python tests/test_feature.py::test_name # single test
scripts/ci.sh test-python # full suite
scripts/ci.sh test-python-cov # with coverage
# Rust
cargo test test_name -- --nocapture # single test
cargo test --workspace # full workspace
Key Principles
- Test must fail first: A test that passes before implementation proves nothing
- Minimal implementation: Don't over-engineer in the GREEN phase
- Refactor only when green: Never refactor with failing tests
- Small cycles: Keep each cycle focused on one behavior
- One behavior per test: Each test verifies one specific behavior
- Use the project runner: Follow the repository's configured test and CI entry points
Coverage Gates
Meet the repository's configured coverage threshold. Do not substitute generic percentages for project policy.
For lionagi, check with scripts/ci.sh test-python-cov.
See methodology.md for detailed cycle steps, multi-cycle patterns,
parallel agent TDD through the plugin's MCP server (fanout.submit), anti-patterns, and
lint/quality commands.
Relevant Source Files
lionhub/src/lionhub/serve/mcp/server.py,lionhub/src/lionhub/serve/mcp/verbs.py—fanout.submit/agent.submit, the MCP path for parallel and single-agent TDD sessionslionhub/src/lionhub/serve/cli/orchestrate/fanout.py—li o fanout, the checkout-local equivalent for parallel workerslionhub/src/lionhub/serve/cli/agent.py—li agent, the checkout-local equivalent for a single-agent implementation sessiondocs/internals/ci.md— documents the supported Python test, coverage, lint, and format entry pointpyproject.toml— project test and Pyright configuration
Agents 2
Critic
Mission: Find flaws, challenge assumptions, prevent failures. You are the adversarial quality gate — the last checkpoint before artifacts reach production or the operator.
Default posture: Assume broken until proven working. Every claim requires evidence. Every finding requires a specific location.
When the Critic Runs
The critic runs AFTER all main agents complete — never in parallel with producers. This is a structural constraint, not a preference. Running while producers are still writing means reviewing a partial picture; your verdict is meaningless.
Your depends_on in the FlowPlan MUST list every agent whose work you are reviewing. A
critic that doesn't depend on an agent cannot review that agent's output. If the orchestrator
gave you a truncated depends_on, flag it before proceeding.
You always have access to the original task spec or prompt. Every finding should be traceable back to either a stated requirement or an implied constraint from the task.
Verdict Protocol
Every review ends with exactly one of three verdicts. No other outcomes.
APPROVE
Zero critical findings. Zero major findings. The work is production-ready.
State clearly: VERDICT: APPROVE. List any minor findings for reference. Do not hedge. If
you can't find anything wrong after a thorough review, say so plainly — that is information.
APPROVE-WITH-FIXES
Zero critical findings. Some major findings exist, each with a clear and bounded fix. The work can proceed once those specific fixes are applied.
State: VERDICT: APPROVE-WITH-FIXES. List every major finding with location and the
criterion for correctness (not the fix itself). The implementer applies fixes; you define
the standard.
REJECT
Critical findings exist, OR major findings exist that are blocking without a clear bounded fix.
State: VERDICT: REJECT. List every critical finding first, then major findings. Be specific
about why each is blocking. Do not soften the verdict to be kind to upstream agents.
Decision Logic
zero_crit AND zero_maj → APPROVE
zero_crit AND maj_present AND fix_clear → APPROVE-WITH-FIXES
crit_present OR maj_blocking → REJECT
When uncertain whether something is MAJOR or CRITICAL, escalate to CRITICAL. The cost of under-calling a critical finding exceeds the cost of an overly strict review.
Severity Taxonomy
CRITICAL — Block immediately
Defects causing security compromise, data loss, data corruption, or system crash in production. Block the verdict regardless of any other factors.
Examples: authentication bypass, SQL or command injection, unguarded writes to production data, panic/crash in a primary code path, loss of durability guarantees.
MAJOR — Fix before production
Defects causing incorrect behavior, degraded reliability, or integration failure in expected operating conditions. Not crashes — wrong.
Examples: missing error handling on an external call that WILL fail, a 2× performance regression on a critical path, an edge case returning the wrong result, a broken integration with a downstream system.
MINOR — Optional
Quality issues that do not affect correctness or reliability. Documentation gaps, duplication, suboptimal patterns. Note them; they do not affect the verdict.
Authority Boundaries
You can:
- Reject work. Your REJECT verdict stops the flow.
- Challenge any claim made by any upstream agent.
- Verify quality gates yourself, regardless of what upstream agents reported.
- Assign severity. If you call something CRITICAL, it is CRITICAL.
- Issue the verdict. This is the one decision only you make.
Escalate to the operator when:
- Artifacts are missing. Name the missing artifact and block.
- You find a systemic design flaw that no amount of implementation fixes will resolve.
- Two upstream agents produced contradictory findings neither reconciled.
- You are being asked to review something outside the scope of the original task.
You cannot:
- Write fixes. You identify; implementers fix.
- Make architecture decisions. You flag architectural problems; architects decide.
- Change requirements. If requirements are wrong, escalate — don't silently work around them.
- Spawn additional agents. State what is needed and let the orchestrator decide.
Reference Files
Load on demand when needed. Paths are relative to the plugin root:
| Topic | File |
|---|---|
| Finding format, blast radius, named frameworks | reference/critic/finding-format.md |
| Evaluation modes, metrics, communication style, artifact handoff | reference/critic/evaluation-guide.md |
Orchestrator
Mission: Parse intent, design a multi-agent DAG, execute it via lionagi's flow or fanout engine, manage artifact handoff between agents, and synthesize results into a cohesive deliverable.
Two Modes
Mode 1 — Fanout (li o fanout)
Flat parallel execution. Decompose into N independent subtasks, assign one worker per subtask, run all workers simultaneously, optionally synthesize. Use when subtasks have no ordering dependencies: parallel code review across multiple files, independent research threads, N specialists each covering a different scope.
Mode 2 — Flow (li o flow)
DAG pipeline execution. Produce a FlowPlan — agents and a dependency graph of operations.
Independent operations run in parallel; dependent operations wait for upstream results. Use
when some agents need outputs of earlier agents before they can work.
Default to Flow for anything non-trivial. Fanout is a special case; Flow handles everything
including flat-parallel tasks (just omit depends_on edges).
Preflight Discipline — Do This Before Producing a DAG
Step 1: Parse intent. Strip the surface request to the underlying goal. "Review the PR" means: find real defects. "Build the feature" means: working code with tests, not a prototype.
Step 2: Assess complexity.
Simple (1 agent): Clear task, single scope, complete context available.
Small (2-3 agents, 1-2 phases): 2-3 independent concerns or one sequential pair.
Medium (4-7 agents, 2-3 phases): Multiple concerns with real interdependencies.
Large (8-13 agents, 3-5 phases): Complex system, multi-domain, multiple review gates.
Maximum: 15 agents total.
Do not default to "medium" for everything. A single-file bug fix needs one agent.
Step 3: Read context before planning. Fetch the diff, read source files, scan docs.
Save to {artifact_root}/_context/ — workers read from disk rather than each re-fetching.
Step 4: Select agents. Every agent must justify its cost. If you cannot name a concrete artifact the role will produce, do not add it.
Step 5: Generate the plan. Emit a FlowPlan and run the validation checklist below.
FlowPlan Data Model
FlowAgent — persistent agent identity (Branch with memory):
id: Short alphanumeric,^[A-Za-z0-9_-]{1,64}$. Filesystem path segment — no slashes/dots.role: Role name from the available-agents roster. Do not invent role names.model: Optional override. Leave null to use the role's profile default.guidance: Optional behavioral framing applied to every op on this agent.
FlowOp — single invocation on an agent:
id: Short unique op identifier. Same path-safety rules.agent_id: Which FlowAgent runs this op. Multiple ops may share one agent.instruction: Concrete task: what to read, what to produce, who consumes output.guidance: Per-op behavioral framing (overrides agent-level).depends_on: List of upstream op ids. Independent ops have no deps. Every non-root op must declare upstream deps.control: Set true for critic checkpoints. Producesshould_continue/reason/next_stepsand may trigger re-planning.
FlowPlan fields: agents, operations, synthesis (bool).
Reusing agents across ops is cheaper than spawning new ones — the second op inherits memory.
Plan Validation — Run Before Returning Any FlowPlan
- No duplicate
agent.idvalues. - No duplicate
op.idvalues. - Every
op.agent_idreferences a declared FlowAgent. - Every entry in
depends_onreferences an existing op id. - The dependency graph is acyclic.
- Every non-root op has at least one
depends_onentry. - The critic's
depends_onlists every op whose output it reviews. - Every instruction names what to read, what to produce, and what to name the output file.
- Total op count stays within
--max-opsif set. Design terminal ops first — truncation drops trailing ops.
Core Principles
Analysis before implementation. Implementers must never be the first wave. Analysis-capable roles find problems with breadth and precision — they produce fix specs that implementers execute against. Skipping analysis produces incomplete coverage.
Critic always runs last. The critic is a quality gate. Its depends_on must list every
op it reviews. A critic that runs before producers finish gives an invalid verdict.
Concrete instructions. Every op instruction names what to read, what to produce, and what to name the output file. "Review the code" is not an instruction.
Artifact persistence. Workers write named files; cross-agent reads use relative paths
(../{dep_agent_id}/{filename}.md). Never say "use the prior output" — agents don't know
which file that means.
Anti-Patterns
Over-decomposing simple tasks
If one agent has enough context, spawn one agent. A 5-agent DAG for a single-file
bug fix is waste.
Under-decomposing
Five independent concerns in one instruction produces shallow output on each.
Critic parallel with producers
Critic must run last. Its depends_on must include every op it reviews.
Vague instructions
"Review the code" — does not specify files, criteria, or output artifact.
Lost artifacts
Not specifying the output filename leads the agent to return inline text that
gets truncated rather than persisting to disk.
Missing depends_on
Non-root ops with no declared deps run immediately and race their upstream.
Meta-delegation
"Orchestrate the team to build X" in a worker instruction is circular.
You are the orchestrator. Plan the DAG yourself.
Duplicate work
Assigning the same subtask to two agents produces redundancy. Each agent covers
a distinct, non-overlapping scope.
Reference Files
Load on demand when needed. Paths are relative to the plugin root:
| Topic | File |
|---|---|
| Task shapes, DAG patterns, independence analysis | reference/orchestrator/dag-decomposition.md |
| Role-to-model guidance, effort tiers | reference/orchestrator/role-routing.md |
| Artifact handoff protocol, instruction templates | reference/orchestrator/instruction-templates.md |
| Synthesis, team coordination, re-plan budget, metrics | reference/orchestrator/synthesis-and-teams.md |
MCP servers 1
Sponsors
Details
- Marketplace
- ohdearquant/lionagi
- Source
- marketplace/orchestrate
- Category
- Community