Multi-agent orchestration for lionagi: plan DAG workflows, author playbooks, run multi-play shows with quality gates.

GitHub stars
412

Install

/plugin install orchestrate@lionagi

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ohdearquant/lionagi.

Contents

Discovered from source

Skills 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

PhaseActionGate
1. ResearchCheck prior runs, search codebase, spawn researcher agent2-3 focused queries before any fix attempt
2. OrchestrateParallel diagnostic agents via fanout.submit, or a focused agent via agent.submitAgent must produce actionable insight
3. EscalateGenerate consultation request with full evidenceMust demonstrate exhaustive research first
4. DocumentWrite fix to ./notes/debug-log.mdOnly 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 of agent.submit
  • lionhub/src/lionhub/serve/cli/orchestrate/fanout.py — li o fanout, the CLI counterpart of fanout.submit
  • lionhub/src/lionhub/orchestration/runs.py — run persistence at ~/.lionagi/runs/, also readable through job.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_workers caps the initial independent assignments; the planner may produce fewer.
  • fanout.submit is a fixed fanout. Its current schema has no reactive, max_ops, or dry_run argument, so do not pass those names.
  • For reactive discovery, use flow.submit. Its spawn capacity is max_ops - initial assignment count when max_ops is nonzero. A plan that fills max_ops has no capacity left for follow-ups; reserve headroom and verify the initial plan with dry_run: true.
  • Ops in one request run in order. A failed op returns ok=false without 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

SituationVerb
Single task, one agentagent.submit
Same prompt to N independent workersfanout.submit
Staged pipeline with dependenciesflow.submit
Pre-saved parametric workflowplay.submit
Check on a run already submittedjob.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=true in its own call, before writing a spawn call — never combine help and ops in one call; the server refuses it.
  • schema_fingerprint rides as a sibling of args, never inside it — every *.submit verb requires it, fetched from help.
  • Named profiles are installation-specific — call profile.list before passing agent, or pass a model through the verb's positional query argument 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_on only for real data dependencies — independent assignments leave it empty and run concurrently.
  • Reserve reactive capacity — max_ops is shared by the initial plan and follow-up spawns; a plan that fills it leaves no room for reactive work.
  • dry_run is a text preview — it does not build a run graph. show_graph writes a graph artifact only after an executing flow finishes.
  • The catalog is the authority, not this bundle — reference.md documents 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=true settles 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_fingerprint protocol, and the secondary li CLI flag tables
  • dag-planning.md — TaskAssignment data 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:

ComponentPath
MCP server + verb cataloglionhub/src/lionhub/serve/mcp/server.py, lionhub/src/lionhub/serve/mcp/verbs.py, lionhub/src/lionhub/serve/mcp/dispatch.py
CLI entrypointlionhub/src/lionhub/serve/cli/main.py
Flow engine (TaskAssignment DAG)lionhub/src/lionhub/serve/cli/orchestrate/flow.py
Fanout enginelionhub/src/lionhub/serve/cli/orchestrate/fanout.py
Argparse definitionslionhub/src/lionhub/serve/cli/orchestrate/__init__.py
Agent CLIlionhub/src/lionhub/serve/cli/agent.py
Teamslionhub/src/lionhub/serve/cli/team.py
Invocationslionhub/src/lionhub/serve/cli/invoke.py
Scheduler enginelionhub/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

  1. Ask for the catalog in its own call and confirm play.submit is available:

    mcp__plugin_orchestrate_lion__request(help=true)
    
  2. 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"})
    
  3. Copy that reply's schema_fingerprint into the op as a sibling of args:

    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: true inside args to plan without executing workers. The dry run is still a background job, so inspect it through job.status and job.output.
  • If calling flow.submit with a playbook instead, use the same qualified-help rule with {"verb": "flow.submit", "playbook": "<same name>"}.
  • Multiple ops run in order, but one op returning ok=false does not stop its siblings. Check every op's ok field 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: and agent: are optional; when both are omitted, flow uses its default orchestrator configuration. If agent: is set, verify that profile exists on the machine running the MCP server
  • prompt: references only declared args keys and optional {input}
  • Every args entry declares type, default, and help. A supplied type is validated; omitting these fields yields str, null, and a generated help line respectively
  • No dashed keys inside args:
  • team_mode and team_attach are not both set
  • workers is 1–32 if set; max_ops is 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.submit with dry_run: true plans without executing (call help=true first to confirm the argument name for your published server version)
  • Help check (lionagi checkout only): li play <name> --help always lists fields from args:; argument-hint controls the usage line and can define fallback flags when no args: block exists. Over MCP, qualified playbook help resolves the custom arguments

Companion Files

FileContents
field-reference.mdComplete field table, args schema, template interpolation rules, team semantics, reserved names, pitfalls, source code reference
examples.mdThree annotated example playbooks (minimal, audit, pr-review) plus the examples directory index
patterns.mdOrchestration 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

PhaseAction
0. Fetch contextgh pr view + gh pr diff → save to _context/
1. DiscoveryParallel specialists from closed set (correctness, security, architecture, tests, perf)
2. DiscussionOptional — only if dimensions cross-pollinate
3. Critic synthesisReads all findings → critic_final/final_synthesis.md
4. Post commentONE consolidated comment per verbosity tier

Verdict options

APPROVE | APPROVE-WITH-FIXES | REJECT

Verbosity tiers for posting

VerbosityContentSafe for
nonedon't post, synthesis stays localany
brief≤10 lines: verdict + top MUST-FIX onlyOSS
substantiveMUST-FIX + SHOULD-FIX with file:line; omit blind-spotsinternal repos
fullcomplete synthesis including blind spots + coverageprivate repos only

Ground rules

  1. Cite line numbers against committed HEAD of the PR branch.
  2. Don't invent requirements — only flag if absence is a bug.
  3. If runtime context is needed that isn't in the diff, say so.
  4. Graceful degradation — note any tool failures in synthesis.

Related skills

  • security-review — threat-model rubric for the security dimension
  • review — 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)

  1. Correctness — logic, control flow, off-by-one, error handling, invariants, concurrency, numeric
  2. API contract — backward compatibility, type annotations, error types, return value shape
  3. Tests — coverage of new paths, edge cases, mock fidelity, flaky risk
  4. Readability & maintainability — names, function length, nesting, comments, dead code
  5. Consistency — naming convention, error handling pattern, import ordering, abstraction level
  6. Docs & changelog — public API changes, behavioral changes, new config options
  7. Dependencies — necessity, maintenance, license, version constraints, lockfile
  8. Performance (light-touch) — obvious O(n²) regressions, hot-path allocations, N+1 queries
  9. 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:

SeverityLocationIssueSuggested fixConfidence
MEDIUMsrc/module.py:87Off-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 merge
  • HIGH — correctness bug affecting real use cases
  • MEDIUM — edge case bug, significant maintainability issue
  • LOW — style, naming, minor refactor
  • INFO — future consideration, not blocking

Ground rules

  1. Describe the bug, propose a fix.
  2. Don't invent requirements.
  3. Rank severity honestly.
  4. Flag assumptions you can't verify from the diff.
  5. 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)

  1. Authentication & authorization — endpoint auth checks, session tokens, RBAC, fail-closed, multi-tenant
  2. Input validation — type/range/length/encoding, parameterization, regex anchoring, structured data parsers
  3. Data exposure — error messages, logs, response fields, timing/cache leaks
  4. Crypto & secrets — hardcoded keys, safe defaults, weak primitives, random vs secrets, password hashing
  5. Injection — SQL, shell, LDAP, template, HTML/XSS
  6. File / path handling — path containment, zip-slip, temp files, symlinks
  7. Supply chain — typosquatting, pinned versions, endpoint validation
  8. Deserialization & parsers — pickle, yaml.load, eval, exec, XXE
  9. Race conditions / TOCTOU — atomic file operations, lock scope
  10. 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 exposure
  • HIGH — data exposure / auth gap requiring specific conditions
  • MEDIUM — mis-scoped tokens, weak validation, missing rate limit
  • LOW — defense-in-depth hardening
  • INFO — 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

SeverityLocationDescriptionSuggested fixConfidenceRuntime-context caveats
HIGHfile.py:112Path not containment-checkedCanonicalize, enforce containment, and use race-resistant accessHighSymlink 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

  1. Don't invent requirements.
  2. Flag runtime context you need but can't see.
  3. Be honest about confidence.
  4. 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

Dimensionflow.submitshow (this skill)
ExecutionOne dependency DAGMultiple gated playbook runs
Unit of workPlanned assignmentFull playbook run (play.submit)
BranchingSingle DAGEach play gets its own worktree + branch
Human gateOptional critic nodeBetween every play
ReplanningWorker-triggered reactive spawn requestsAfter every play based on verdict
Studio surfaceFleet/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

  1. Plan — Write _show.md (goal, plays, deps). Create the integration branch off main.
  2. Pick — Select the next play: pending status, all depends_on plays are merged.
  3. Worktree — git worktree add -b show/<topic>/<play> off the integration branch.
  4. Fire — Call play.submit for the playbook; record the returned run_id.
  5. Gate — Call agent.submit with the acceptance criteria; write _verdict.json.
  6. Decide — gate_passed=true → merge; attempt 1 fail → redo; attempt 2 fail → escalate.
  7. Adapt — Update _show.md decisions; adjust downstream _intent.md if outputs changed.
  8. 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/plays table schema, status enums, reading a show from Studio
  • procedure.md — full 8-step procedure with the MCP calls, workspace layout, _show.md format
  • gate-protocol.md — gate agents, verdict JSON, decision logic, abort/resume

Source code reference

FilePurpose
lionagi/state/schema.sql (CREATE TABLE shows, CREATE TABLE plays)shows and plays table DDL
lionagi/studio/services/shows.pyList, detail, import, SSE watcher, and the /api/shows routes
lionagi/studio/registry.pyRegisters that service with the app
lionagi/studio/config.pyLIONAGI_SHOWS_ROOT and the root it falls back to
apps/studio/frontend/src/components/shows/PlayDag.tsxDAG visualization component; present in the tree, imported by nothing
lionhub/src/lionhub/serve/mcp/server.py, lionhub/src/lionhub/serve/mcp/verbs.pyMCP 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:

TriggerAction
Decision madeRecord decision + rationale + alternatives considered
Pattern discoveredNote the pattern with "when to use" conditions
Significant work completedCapture what was done + outcome
Problem solvedRecord approach + what worked / what didn't
Session winding downOffer to run a full session summary or auto-capture key points
Topic switchQuick 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 sessions
  • lionhub/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 artifacts
  • lionhub/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

PhaseActionGate
REDWrite failing test expressing desired behaviorRun it — MUST fail. If it passes, it tests nothing new.
GREENWrite minimum code to make the test passRun it — MUST pass. No over-engineering.
REFACTORClean up while staying greenRun 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 sessions
  • lionhub/src/lionhub/serve/cli/orchestrate/fanout.py — li o fanout, the checkout-local equivalent for parallel workers
  • lionhub/src/lionhub/serve/cli/agent.py — li agent, the checkout-local equivalent for a single-agent implementation session
  • docs/internals/ci.md — documents the supported Python test, coverage, lint, and format entry point
  • pyproject.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:

TopicFile
Finding format, blast radius, named frameworksreference/critic/finding-format.md
Evaluation modes, metrics, communication style, artifact handoffreference/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. Produces should_continue / reason / next_steps and 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

  1. No duplicate agent.id values.
  2. No duplicate op.id values.
  3. Every op.agent_id references a declared FlowAgent.
  4. Every entry in depends_on references an existing op id.
  5. The dependency graph is acyclic.
  6. Every non-root op has at least one depends_on entry.
  7. The critic's depends_on lists every op whose output it reviews.
  8. Every instruction names what to read, what to produce, and what to name the output file.
  9. Total op count stays within --max-ops if 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:

TopicFile
Task shapes, DAG patterns, independence analysisreference/orchestrator/dag-decomposition.md
Role-to-model guidance, effort tiersreference/orchestrator/role-routing.md
Artifact handoff protocol, instruction templatesreference/orchestrator/instruction-templates.md
Synthesis, team coordination, re-plan budget, metricsreference/orchestrator/synthesis-and-teams.md

MCP servers 1

Sponsors

Details

Marketplace
ohdearquant/lionagi
Source
marketplace/orchestrate
Category
Community