
leo-skills
Collection of custom skills: leo-wiggum for autonomous AI coding loops with phased execution, browser validation, and quality ratcheting; grok-x-research for live X (Twitter) and web research through the Grok CLI; orchestrating-codex for delegating implementation, diagnosis, and review to Codex/GPT; claude-cli for invoking and resuming Claude Code sessions from Codex; agentbus for file-based multi-agent debates that reach a recorded consensus
Install
/plugin install leo-skills@leo-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add LeomaiaJr/leo-skills.
Contents
Discovered from sourceSkills 5
agentbus
Turn-taking message bus for multi-agent debates. A thread is a directory of immutable message files; the agentbus CLI derives phase and turn from those files and refuses out-of-turn posts. No agent launches another. Every participant, whatever its harness, only runs shell commands.
CLI: agentbus on PATH (canonical copy: ~/Leo/Dev/agentbus/agentbus). agentbus help lists every command.
Roles
- Participant (most common): you were handed a participant prompt, or asked to "join thread X as " or to "discuss this with ". Follow the participant loop.
- Creator or moderator: asked to set up a debate between agents, hand out prompts, steer, or read the outcome. See "Creating a thread".
Your participant name is your product name in lowercase (claude, codex, gemini, cursor, opencode, copilot) and must match a line in the thread's participants file. The human posts as user.
If you were given an AGENTBUS_ROOT (in the prompt, or because the thread is not in the default location), export it before every agentbus command. Commands printed by prompt and wait already carry it.
Participant loop
agentbus status <thread>for phase, whose turn, and the topic. Do not read the transcript yet.- Investigate on your own first, so positions are independent. Then post exactly one
findingwith evidence and file:line references. Only now runagentbus read <thread>to see what the others found. - Wait for your turn (see Waiting).
- On your turn, read what is new, then post exactly one message:
argue,propose,disagree,agree, orquestion. Always pass--re <id>;agreemust reference the current proposal. Accept a correction when the evidence supports it, and say so. - Repeat 3 and 4 until convergence. Do not restate settled points; when you accept a counter-proposal with amendments, post a fresh
proposethat folds them in rather than a partialagree. In v1 a proposal does not count as its author's agreement: once the others have agreed to your proposal, postagree --re <your own proposal id>yourself, or the thread never reaches ALL AGREED. - When wait reports ALL AGREED and names you, post
consensus --re <proposal id>quoting the accepted proposal and the key reasons. When wait reports CLOSED, report the consensus to the human and stop.
Multi-line bodies go on stdin instead of -m:
agentbus post <thread> <me> argue --re 0004 <<'MSG'
...
MSG
Waiting
- Harness with a background monitor that turns stdout lines into notifications (Claude Code: the
Monitortool, persistent): runagentbus watch <thread> <me>under it and keep working. It emitsNEW <id> <from> <type> <path>,TURN <me> phase=<phase>, andCLOSED <thread>, then exits. Act onTURN. - Any other harness: run
agentbus wait <thread> <me> --timeout <seconds>and do nothing else until it returns. It prints the new messages and the exact reply command. It prints TIMEOUT and exits 124 when the timeout elapses: run the same command again. Choose a timeout below your harness's per-command limit.
Creating a thread
agentbus new <thread> claude,codex "<question, decision criteria, and the deliverable>"
agentbus prompt <thread> codex # paste the output into that agent's terminal
agentbus post <thread> user user -m "moderator note" # any time, consumes no turn
Participant order is speaking order, and the first participant writes the consensus. Threads default to ~/Leo/Dev/agentbus/threads; set AGENTBUS_ROOT for a per-project location and give every participant the same value.
Constraints
- The CLI is the only writer. Never edit or create files under a thread by hand.
- One post per turn. Do not use
--force; it exists for the human moderator only. - v1 limitation: two agents posting within the same second can collide on message ids. In the investigate phase, check
agentbus statusand wait a few seconds if the other agent is likely mid-post. - Do not spawn or drive another agent's CLI. The thread is the only channel.
For the message format, phase and turn rules, wait output, exit codes, and the v1 limitations and roadmap, read references/protocol.md.
Claude CLI
Use the locally installed Claude Code CLI as a bounded collaborator from Codex.
Before invoking
- Run
command -v claudeandclaude --version. If a required flag is uncertain, inspectclaude --help; the installed CLI is the authority for what can run locally. - Run Claude in the directory whose project context it should see.
claude -pskips the workspace-trust dialog, so use it only in a directory the user has placed in scope and that you trust. - Invoking Claude does not expand the user's authorization. Limit tools and permissions to the task. Never add
--dangerously-skip-permissionsunless the user explicitly authorizes that behavior.
Preferred Codex workflow
For a new non-interactive session, request JSON so both the response and session ID are machine-readable:
claude -p --output-format json --model sonnet "Inspect the scoped change and summarize it."
Read .result, .session_id, .is_error, .subtype, and cost/usage fields from the JSON. When jq is available:
claude_json=$(claude -p --output-format json "First request")
claude_session_id=$(printf '%s' "$claude_json" | jq -r '.session_id')
printf '%s' "$claude_json" | jq -r '.result'
Append a new user message to that exact conversation by resuming its ID:
claude -p --output-format json --resume "$claude_session_id" "Follow-up request"
Resuming writes the follow-up into the same session and normally returns the same session_id. Prefer an explicit ID over --continue when more than one Claude conversation may exist. Use --fork-session with --resume when the original transcript must remain unchanged.
For answer-only calls that should not inspect or modify the workspace, disable built-in tools:
claude -p --tools "" --output-format json "Answer without using tools: ..."
For coding work, select only the needed tools with --tools, --allowedTools, --disallowedTools, and an appropriate --permission-mode; do not silently weaken approvals.
Model selection
Pass --model <alias-or-full-id> on a new call or resume. Aliases such as sonnet and opus track Anthropic's current model mapping and can change; use a full model ID when reproducibility matters. A resumed session otherwise restores its prior model when available. Confirm the actual model from the JSON modelUsage object rather than assuming an alias's current target.
Session details
--continueresumes the most recent eligible conversation;-p --continueincludes print-mode sessions, while the interactive picker and ordinary interactive--continueomit sessions created with-p.--session-id <uuid>assigns a valid UUID to a new conversation. It does not mean resume; use--resume <id>to continue an existing conversation.- Do not use
--no-session-persistencewhen later resume is required. --output-format stream-jsonis for event-by-event processing. Usejsonfor a single structured result andtextonly when no metadata is needed.- Keep shell quoting intact, use a task-specific variable name, and avoid dumping full JSON when it may contain sensitive prompts or tool output.
Read references/commands.md when the task needs the command matrix, session-discovery details, streaming input, or source links.
Report back
State the CLI version, selected/resolved model when relevant, whether the call succeeded, the useful result, and the session ID if the user needs to continue it. Mention cost only when the JSON exposes it and it is useful; do not claim billing behavior beyond the returned fields.
Grok X Research
Grok's search reaches live X (Twitter) posts and the web, and returns real author handles with real x.com/<handle>/status/<id> URLs. This is the fastest way to learn what practitioners are actually doing right now, as opposed to what documentation claims.
The binary is grok
grok -p "<your research prompt>"
That is the whole interface. It prints the answer to stdout and exits, typically in 30–60s.
grok-cli is a different, unrelated community tool, and usually is not installed. If you find yourself typing grok-cli, or curling an installer from GitHub, stop — you want the grok binary already on PATH. Confirm with grok --version.
Write the prompt with all four parts
Every research prompt you send must contain:
- The source, named — "Search X (Twitter) for…". Naming X shifts what gets searched.
- A time window — "in the last 7 days", "since ". Without one you get evergreen filler.
- The output shape — "Return N posts, each with the author handle, the date, one concrete claim, and the direct x.com URL."
- An honesty clause — "If you cannot find real posts, say NO_RESULTS instead of inventing any. List what you could not confirm."
Dropping part 2 or 3 is the usual reason a run comes back vague.
grok -p 'Search X (Twitter) for what engineers posted in the last 7 days about how they
are running AI agents in production. Return 5 posts, each with the author handle, the
date, the specific technique or failure described, and the direct x.com URL. Then list
what you could NOT confirm. If you cannot find real posts, say NO_RESULTS.'
See references/prompt-recipes.md for ready templates: trend scans, "how are people building X", tool reception, launch checks, and tracking a specific account.
Report what Grok returned, with its links
Your answer to the user is built from what came back:
- Each substantive claim carries the handle and the
x.comURL Grok gave for it. - Dates stay attached — "posted 2026-07-24", not "recently".
- A short Gaps line covering what Grok said it could not confirm.
- Distinguish one person's opinion from a broadly repeated pattern. A single post is one practitioner's take; say so rather than promoting it to a trend.
Do not add posts, handles, or URLs that Grok did not return. If a claim matters and is cheap to check, open the URL and confirm before repeating it.
Two things that do not work
--json-schema is unreliable for research prompts. In testing it returned structuredOutput: null with a parse error while the real answer sat in the text field. Use plain output and read it. If you need machine-readable results, ask for a fenced JSON block inside the normal prompt.
grok with no -p needs a real terminal. Non-interactive it exits with Error: Device not configured. Always pass -p.
If your sandbox blocks it
Grok writes a session file under ~/.grok on every run. A sandbox that denies writes there fails immediately with:
Couldn't create session: Permission denied.: {"code": "FS_PERMISSION_DENIED"}
The fix is to allow writes to ~/.grok. If you cannot, relocate the whole home — and copy both files:
export GROK_HOME=/writable/path/grokhome
mkdir -p "$GROK_HOME" && cp ~/.grok/auth.json ~/.grok/config.toml "$GROK_HOME"/
grok --always-approve -p '<prompt>'
Copy both or it gets worse, not better. An empty GROK_HOME exits with Not signed in; a half-populated one can sit silently for minutes. Grok printing nothing for minutes is a broken environment, not a slow search — a normal run answers in 30–60s. Kill it and fix the home directory rather than retrying with more flags.
Do not set GROK_HOME when ~/.grok is already writable.
Going deeper
For a question that deserves parallel investigation and claim-by-claim verification rather than a single answer, Grok has a built-in deep-research workflow. It costs several minutes and many model calls, and launching it headlessly the obvious way silently returns an empty report — read references/deep-research.md before using it.
Reach for it only when a single grok -p has come back thin, or the question is genuinely multi-part. Most requests do not need it.
Fast checks
| Situation | Action |
|---|---|
command not found: grok-cli | Wrong binary. Use grok. |
Error: Device not configured | You omitted -p. |
| Empty / generic answer | Add a time window and demand handles + URLs. |
FS_PERMISSION_DENIED | Sandbox blocks ~/.grok. See above — do not improvise a new GROK_HOME. |
| Silent for minutes, no output | Broken environment, not a slow search. Kill it and fix the home directory. |
Not signed in | GROK_HOME points somewhere without auth.json. |
| Deep-research report says "Status: Partial / No supported factual answer" | The session exited early. See references/deep-research.md. |
Leo Wiggum v2 - Autonomous AI Coding Loop
Phased, skill-aware autonomous coding loop with browser validation, structured memory, and quality ratcheting. Works on any project or from scratch.
How It Works
- Phase 0 — Discovery/Scaffold: Analyze codebase or scaffold a new project
- Phase 1 — Foundation: Core infrastructure stories (schema, auth, config)
- Phase 2 — Features: Story-based implementation with dependency ordering
- Phase 3 — Polish & Validation: Integration validation, browser smoke tests, cleanup
- Each iteration agent receives skill assignments and structured memory from previous iterations
- Memory persists via
.leo/directory (prd.json, memory.json, quality-metrics.json, screenshots)
Usage
Parse from user input:
- prompt (required): Feature or project description
- --max-iterations N: Max iterations (default: 15)
- --branch name: Git branch (default:
leo/<feature-slug>) - --greenfield: Force greenfield scaffolding mode
- --headed: Run browser validation in headed mode (visible)
Step 1: Discovery / Scaffold
Existing Project
- Read
CLAUDE.mdif exists - Detect tech stack by checking:
package.json,Cargo.toml,pyproject.toml,go.mod,requirements.txt,Makefile, etc. - Explore code structure with Glob/Grep to understand patterns
- Identify and populate
techStackin PRD:language,frameworkbuildCmd,testCmd,lintCmd,typecheckCmddevServerCmd,devServerUrl
- Run baseline quality check (typecheck, tests, lint) and record in
quality-metrics.json
Greenfield (--greenfield flag or no recognizable project files)
- Infer desired stack from the user's prompt (or ask if unclear)
- Generate scaffold story as first Phase 1 story (
US-000: Initialize project scaffold) - ALL other stories
dependsOn: ["US-000"] - Set
techStackwith expected commands for the chosen framework - Quality baseline is captured AFTER the scaffold story passes
Step 2: Generate Phased User Stories
Break the feature/project into stories organized by phase. Each story must be completable in ONE iteration.
Skill Assignment
Assign 1-3 skills per story based on its content:
| Skill | When to Assign |
|---|---|
code | Always — general implementation |
database | Schema changes, migrations, seed data |
api | API endpoint creation or modification |
ui | Frontend component work |
browser | Story has visual output to validate |
test | Test-focused or test-heavy stories |
Right-Sized Stories
- Add database model + migration
- Add single UI component or page
- Create one API endpoint
- Add form with validation
- Write tests for one module
Too Big (must split)
- "Build entire dashboard" -> split into individual pages/components
- "Add authentication" -> split into model, API, UI, tests
- "Refactor API" -> split by domain/router
Dependency Graph
- Stories declare
dependsOn: ["US-XXX"]for explicit ordering - The iteration loop only picks stories whose dependencies are all
passed - Avoid circular dependencies
Browser Validation
For UI stories, add validation.type: "browser" with steps:
{
"validation": {
"type": "browser",
"browserSteps": [
{ "action": "open", "target": "http://localhost:3000/page" },
{ "action": "wait", "target": "--text 'Expected Text'" },
{ "action": "snapshot", "expect": "description of what should be visible" },
{ "action": "screenshot", "path": ".leo/screenshots/US-XXX.png" }
]
}
}
Step 3: Create .leo/ Directory
Initialize the following files in .leo/:
.leo/prd.json
{
"version": 2,
"project": "<project name>",
"branchName": "leo/<feature-slug>",
"description": "<feature/project description>",
"techStack": {
"language": "<detected>",
"framework": "<detected>",
"buildCmd": "<detected or null>",
"testCmd": "<detected or null>",
"lintCmd": "<detected or null>",
"typecheckCmd": "<detected or null>",
"devServerCmd": "<detected or null>",
"devServerUrl": "<detected or null>"
},
"phases": [
{ "id": "phase-0", "name": "Discovery", "type": "discovery", "status": "complete" },
{ "id": "phase-1", "name": "Foundation", "status": "pending" },
{ "id": "phase-2", "name": "Features", "status": "pending" },
{ "id": "phase-3", "name": "Polish", "status": "pending" }
],
"stories": [
{
"id": "US-001",
"title": "<title>",
"description": "As a <user>, I want <goal>, so that <benefit>",
"phase": "phase-1",
"priority": 1,
"skills": ["code", "database"],
"dependsOn": [],
"status": "pending",
"failureCount": 0,
"maxRetries": 3,
"acceptanceCriteria": [
"<criterion 1>",
"<criterion 2>"
],
"validation": {
"type": "none",
"browserSteps": []
},
"notes": "",
"lastFailure": null
}
]
}
.leo/memory.json
{
"patterns": [],
"decisions": [],
"failures": [],
"environment": {}
}
.leo/quality-metrics.json
Run the project's quality commands and capture baseline:
{
"baseline": {
"typescriptErrors": 0,
"testCount": 0,
"testPassRate": 1.0,
"lintErrors": 0,
"buildSuccess": true
},
"snapshots": [],
"ratchetRules": {
"typescriptErrors": "no-increase",
"testCount": "no-decrease",
"testPassRate": "no-decrease",
"lintErrors": "no-increase",
"buildSuccess": "must-be-true"
}
}
For greenfield projects, set all baseline values to 0/true (baseline captured after scaffold story).
Also create .leo/screenshots/ directory.
Step 4: Show Summary & Confirm
Display to the user:
- Phase breakdown with story counts per phase
- Dependency graph (which stories block which)
- Skill distribution across stories
- Quality baseline (if existing project)
- Branch name
- Max iterations
- Command that will run
Step 5: Start Loop
Ask user to confirm, then run:
${CLAUDE_PLUGIN_ROOT}/scripts/leo-wiggum.sh <max_iterations>
Pass --headed if user requested visible browser.
CRITICAL: After starting the script, END your response immediately. The script spawns NEW Claude Code sessions — your job is done.
Monitoring
- Terminal: phase/iteration progress, quality gate results
.leo/prd.json: story statuses and failure info.leo/memory.json: structured learnings, patterns, decisions, failures.leo/quality-metrics.json: metric trends across iterations.leo/screenshots/: visual proof from browser validationgit log: commits per story
Orchestrating Codex
Claude is the tech lead. Codex is the implementer and the reviewer. The lead scopes, decides, and accepts or rejects; the lead does not become the only pair of hands in the room.
Requires the codex@openai-codex plugin. If Codex is missing or unauthenticated,
say so and stop — do not silently absorb the work.
What the lead keeps
Never delegate these:
- Framing — what the actual problem is, and the root cause behind the symptom.
- Approach — architecture, the shape of the fix, which tradeoff wins.
- Acceptance — reading Codex's diff and deciding whether it ships.
- The user relationship — what gets reported, and how honestly.
What goes to Codex
Delegate via the codex:codex-rescue subagent (defaults to --write, so it
edits files):
| Situation | Why Codex |
|---|---|
| Approach is decided, execution spans several files | Mechanical breadth, no judgment left to spend |
| Two of the lead's fix attempts failed | A fresh model beats a third hypothesis from the same one |
| Independent second diagnosis wanted before committing to a theory | Divergence is the point |
| Non-document coding work the lead would otherwise grind through | Matches the standing routing preference |
Keep in-house instead when:
- The task is document, PDF, or extraction analysis — that routes to Claude/Opus, always.
- The task needs MCP tools (Linear, PlanetScale, PostHog, Langfuse, Slack, browser). The Codex runtime is Bash-only; it cannot reach them.
- The handoff costs more than the edit. A one-file change is not a rescue.
- The next move is a decision, not a keystroke.
Writing the handoff
Codex CLI reads the repo's AGENTS.md / CLAUDE.md natively. Do not re-paste
project invariants into the prompt — name the constraint that actually binds this
task and let the file carry the rest.
A handoff states: the goal, the root cause if already known, the files in scope, and what "done" means. It does not include a solution the lead has not committed to, and it does not include hedging.
Review before it ships
Two layers, different jobs:
- Stop review gate (
/codex:setup --enable-review-gate, per-workspace) — Codex reviews every edit-producing turn and can returnBLOCK. This is the safety net; it runs without being asked. /codex:adversarial-reviewbefore opening a PR — challenges whether the approach itself is right. The gate catches defects; this catches wrong designs. It cannot be self-invoked, so the lead must ask the user to run it.
Receiving Codex's output
Codex's verdict is evidence, not a ruling.
- Verify each claim against the repo before acting on it. Confirmed findings get fixed; unreproducible ones get named as such.
- Reject work that violates a project invariant, however confident the diff looks. Acceptance is the lead's signature.
- Report the disagreement when the lead overrides Codex. Silent overrides destroy the value of having a second reviewer.
- A
BLOCKthe lead believes is wrong is a conversation with the user, not a reason to disable the gate.
Red flags
- Delegating because the problem is unclear → clarify first, then delegate.
- Delegating a decision → that is the lead's job.
- Pasting a whole
AGENTS.mdinto a Codex prompt → it already read it. - Accepting a Codex diff unverified → that is not review, that is laundering.
- Doing three hours of grinding implementation solo because delegation felt like admitting defeat → that is the failure this skill exists to prevent.
Sponsors
Details
- Marketplace
- LeomaiaJr/leo-skills
- Category
- Community