xflow
Skill4 starsChanged 5 months agoMITView on GitHub
Run a multi-step workflow template (design → implement → review and similar) that dispatches each step to an external coding-agent CLI via xagent, pauses for human review and orchestrator steps, and keeps every agent trace out of the current context. Use for /xflow commands or when the user wants a multi-agent pipeline on a task.
In this repositoryOne other file it gives its agents.
- xagentSkill
The file
Files
xflow
Drive a multi-step agent workflow from a Markdown template. The flow tool (scripts/xflow_run.py) does all mechanics — rendering, dispatch through xagent, artifact wiring, snapshots, state — one step per call, and returns control to you after every step with its status, a bounded summary, and the pre-rendered next command. You judge every transition; usually you just run the next: line.
Requires the xagent skill (the tool finds it via $XAGENT_RUN, the sibling skill directory, or ~/.claude/skills/xagent).
Commands
/xflow # list templates + show any active flows
/xflow [<template>] <task…> # start a flow; ask for a template if omitted
/xflow continue [<flow-dir>] # resume an existing flow
/xflow status [<flow-dir>] # progress overview
/xflow new <name> <description> # author a new templateInvoke the tool with python3 by its absolute path (<skill>/scripts/xflow_run.py), from the user's project directory. It always exits 0 — branch on the action: line, never the exit code. Every flow-driving output (start, step, human, rerun, status) ends with action: and (unless done) a ready-to-paste next: command; templates ends with its listing and validate with a result: line.
/xflow→ runtemplatesand, if a.xflows/directory exists, list its subdirectories; show both./xflow [<template>] <task…>— any arguments other than thecontinue/status/newverbs mean "start a flow". A leadingrunis accepted for backward compatibility and skipped; it is never required. First determine whether the user selected a template. Runtemplateswhen needed to know valid names. Treat the first argument as a selected template only when it exactly matches a listed template name, is an existing template path, or ends in.md; then runstart --template <name-or-path> --task "<task>"and drive the loop (below). If no template was selected, treat the full remainder as the task, show the available templates fromtemplates, ask which flow template to use for that task, and end your turn without starting a flow. After the user chooses, start with the chosen template and the saved task text./xflow continue→status --flow <dir>(if no dir given, pick the most recent.xflows/*/, confirm with the user), then follow itsaction:/next:./xflow new→ draft a flow file into~/.claude/xflow-flows/<name>.mdfrom the description (seereferences/flow-format.md), runvalidate --template <name>, iterate untilresult: valid, then show the executor table to the user for confirmation.
The protocol
- Start, then drive the loop. Run each returned
next:command. Dispatch steps can take many minutes — runstepin the background and return when it completes. After every step, read the bounded block and judge: usually just continue; a degenerate-but-successful orpartialoutput is your cue to discuss with the user,rerun --step "<id>", or stop. action: orchestrator— execute the printedinstruction:yourself in this thread (invoke the/skill, or do the work). For heavy agent-less steps (research, exploration), delegate to a subagent (Task/Explore) to protect main-thread context. Write the result to the printedartifact:path, then runnext:. The tool detects the artifact and moves on.action: human— collect feedback the way the printedguidance:directs: if it is a/skillinvocation (e.g./cr-review <artifact>), run that skill (unavailable → fall back to chat); if there is no guidance, present thesubject:artifact to the user and ask for feedback in chat, then end your turn. Act on the feedback with judgment:- Targeted comments → edit the subject artifact in place yourself.
- Structural feedback ("the spec is wrong", "do another design round") → edit or rerun earlier steps: fix the earlier artifact directly, or
rerun --flow <dir> --step "<step id>". - User satisfied →
human --flow <dir> --done. Repeat until the user is satisfied. Previous artifact versions are preserved automatically inrevisions/whenever a re-dispatch would overwrite one.
action: error— surface the block (it carries xagent's summary verbatim) to the user and ask:step --retry,step --skip-step(warns when later steps reference the skipped artifact),rerun, or stop.action: done— relay the final per-step table (status, rounds, artifact paths) to the user. Never paste logs; for follow-ups read the artifact files, not stdout/stderr.
Artifacts
Each flow lives in {project_root}/.xflows/{NNN-slug}/: the artifacts (*.md, named after their steps — a container's final document carries the container's name, e.g. design.md), task.md, the frozen template.md, rendered prompts under prompts/, prior versions under revisions/, and machine state in flow.json. Never edit flow.json. Artifacts are ordinary project documents — editing them (e.g. applying review feedback) is normal and expected.
Templates
Resolution order: project .claude/xflow-flows/ → ~/.claude/xflow-flows/ (or $XFLOW_FLOWS) → the skill's assets/flows/. Shipped: design-implement-review, implement-review, explore-brainstorm-design. Format reference: references/flow-format.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

