workflow

Workflow Generator

You generate and execute ad-hoc workflow scripts using the StateGraph engine.

The user's request is: $ARGUMENTS

Engine location

The workflow engine is at: ${CLAUDE_PLUGIN_ROOT}/scripts/engine.py

What to do

1. Read CLAUDE.md and list quality gates. Before anything else, read CLAUDE.md (or AGENTS.md, GEMINI.md) in the repo root. If it exists, extract every quality gate command it mentions (e.g., uv run ruff check ., uv run pyright, npx playwright test, npm run build). Write them down — you will need to add a workflow node for each one.
2. Understand the request. Read relevant source files to understand the codebase context.
3. Design the workflow. Decide which nodes, edges, and routers are needed. Pick the right node type for each step. For every quality gate from step 1, add a dedicated shell_node (or include the command in an LLM node prompt). If CLAUDE.md says "run ruff check", there must be a node that runs ruff. If it says "run pyright", there must be a node for pyright. No exceptions. Look for parallelization opportunities — independent quality gates can run in parallel via add_parallel_edges.
4. Write the script. Create a Python script at /tmp/workflow_NNNN.py (use a random 4-digit suffix). Always include --diagram flag handling (see template).
5. Show the diagram first. Run with uv run /tmp/workflow_NNNN.py --diagram and show the user the rendered ASCII diagram so they can see the workflow graph before execution. The script template already uses graph.to_ascii() for this — do NOT change it to to_mermaid(). The ASCII version renders a visual box-and-arrow diagram directly in the terminal.
6. Run it. Execute with uv run /tmp/workflow_NNNN.py.
7. Report the result. Show the user what happened.

Script template

Every generated script follows this structure:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["mermaid-ascii"]
# ///
import os
import sys
sys.path.insert(0, "${CLAUDE_PLUGIN_ROOT}/scripts")

import asyncio
from engine import (
    StateGraph, claude_node, codex_node, gemini_node,
    shell_node, python_node, template_node,
    detect_available_models, END,
)


def build_graph(models: dict[str, bool] | None = None) -> StateGraph:
    """Build the workflow graph. Accepts optional models dict for testing."""
    if models is None:
        models = detect_available_models()
    HAS_CODEX = models["codex"]
    HAS_GEMINI = models["gemini"]

    graph = StateGraph(max_iterations=5)

    # ... define nodes and edges ...
    # Use codex_node/gemini_node when available and appropriate,
    # fall back to claude_node otherwise. See model selection guide below.

    return graph


if __name__ == "__main__":
    graph = build_graph()
    if "--diagram" in sys.argv:
        print(graph.to_ascii())
        sys.exit(0)
    initial_state = {"work_dir": os.getcwd()}
    asyncio.run(graph.run(initial_state))