agentleFS
pmetelpmetel/xagent-skills/skills/xflow/SKILL.md

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.

The file

Files
SKILL.md

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 template

Invoke 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 → run templates and, if a .xflows/ directory exists, list its subdirectories; show both.
  • /xflow [<template>] <task…> — any arguments other than the continue/status/new verbs mean "start a flow". A leading run is accepted for backward compatibility and skipped; it is never required. First determine whether the user selected a template. Run templates when 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 run start --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 from templates, 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 its action:/next:.
  • /xflow new → draft a flow file into ~/.claude/xflow-flows/<name>.md from the description (see references/flow-format.md), run validate --template <name>, iterate until result: valid, then show the executor table to the user for confirmation.

The protocol

  1. Start, then drive the loop. Run each returned next: command. Dispatch steps can take many minutes — run step in the background and return when it completes. After every step, read the bounded block and judge: usually just continue; a degenerate-but-successful or partial output is your cue to discuss with the user, rerun --step "<id>", or stop.
  2. action: orchestrator — execute the printed instruction: 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 printed artifact: path, then run next:. The tool detects the artifact and moves on.
  3. action: human — collect feedback the way the printed guidance: directs: if it is a /skill invocation (e.g. /cr-review <artifact>), run that skill (unavailable → fall back to chat); if there is no guidance, present the subject: 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 in revisions/ whenever a re-dispatch would overwrite one.
  4. 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.
  5. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.