From piflow
Pi Flow · START — run & monitor an already-created pi-flow workflow on the pi fleet via the SDK CLI, with Claude Code as the single console. LOAD THIS SKILL BEFORE running ANY piflow/pi command — it pins the canonical invocation: the npm-linked global `piflow run <templateDir>` bin (NOT `node …/dist/cli.js` nor `pi-runner/run.mjs`, both non-canonical) with `--provider <gw> --thinking low --sandbox local` + `--from`/`--until`. Do NOT reconstruct the command from memory. Triggers — load on ANY of: "run / kick off / start / resume my piflow workflow", "do a live run on pi", "run game-omni on pi", "companion-mode run", "monitor / follow / poll a run", "diagnose a stalled / never-wrote / blocked node", or the words "piflow" / "pi-runner" / "pi fleet" / "pi run" appearing at all. The run is ALWAYS: pull the next prompt from the bank → dry-run (free) → live background → poll. To CREATE or PORT the template first use piflow-init; to IMPROVE a node/the chain use piflow-enhance.
How this skill is triggered — by the user, by Claude, or both
Slash command
/piflow:piflow-startThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**You are the operator — you run every command; the user runs nothing.** A workflow is a structured TEMPLATE
You are the operator — you run every command; the user runs nothing. A workflow is a structured TEMPLATE
(.piflow/<wf>/template/); the @piflow/core SDK loads it (loadTemplate → instantiateRun → compile → runWorkflow) and runs one pi per node. The entrypoint is the piflow bin (from @piflow/cli,
npm-linked onto PATH — confirm with which piflow). The canonical command is piflow run <templateDir> … —
NOT node <piflow>/packages/cli/dist/cli.js run … (the same code, but the bare-node form is the fallback only
when the link is missing) and NEVER node pi-runner/run.mjs (the deleted legacy monolith). Every command
below (run · inspect · extract · status · watch · logs) is a piflow subcommand.
prompt is the next pending entry of the consumer's
bank (game-omni: eval/prompt-suite.json / the per-archetype sibling), pulled by id. NEVER invent, type,
or paste an ad-hoc prompt — if the prompt you want isn't in the bank, ADD it (status pending) first, then
consume it. On a clean run: flip its status → running and append a runs[] record (flow commit · pi
model · node reached · verdict). Never reuse a prompt across two from-scratch runs.~/.pi/agent/models.json (the first auth-resolved provider = availableModels[0]). Pin it deterministically
with pi's OWN mechanism — ~/.pi/agent/settings.json → { "defaultProvider": "<gw>", "defaultModel": "<id>" } — NOT by layering provider logic in the runner. The pinned default IS ground truth; a stray shell
export (PI_RUNNER_PROVIDER) or a flag must never silently override it. (--provider <gw> on the CLI is the
one allowed EXPLICIT override; passing only --provider with no --model is a pi no-op — it still resolves
to the default model — so prefer pinning settings.json.)--workspace MUST point at the CONSUMER repo (where the skills/templates/registry the node prompts read
live, e.g. /Users/tk/Desktop/game-omni). It resolves the {{WORKSPACE}} tokens in every seed/hook path; a
wrong workspace makes hooks read nothing. The TEMPLATE may live in a different repo (e.g.
piflow/.piflow/game-omni/template) — that's fine; --workspace is what binds the run to the content.--out is the run/project dir ({{RUN}}/{project}) — put it UNDER the consumer's out/ so the
gallery discovers the built game (e.g. /Users/tk/Desktop/game-omni/out/<id>).pi command:
piflow run <templateDir> \
--workspace <consumerRepo> --out <consumerRepo>/out/<id> --run <id> \
--provider <gw> --arg prompt="<the bank entry's prompt>" --dry-run
(piflow is the global linked bin — the consumer repo needs no install; --workspace points it at the
consumer's content. If which piflow is empty, fall back to node <piflow>/packages/cli/dist/cli.js run ….)
CAVEAT: the dry-run prints the FULL DAG; it does NOT show the --from/--until window. The window
applies only at runtime — verify it by reading the matcher, not the dry-run output.--dry-run, add --sandbox local (real in-place pi exec;
omit it and NO model runs — it goes in-memory) and --thinking low (the proven default — omit it
and pi defaults to medium → over-deliberation / stall risk on the headless loop). Redirect to a log and
run in the background:
piflow run <templateDir> \
--workspace <consumerRepo> --out <consumerRepo>/out/<id> --run <id> \
--provider <gw> --thinking low --sandbox local \
--arg prompt="…" [--from <node>] [--until <node>] \
> <consumerRepo>/out/<id>/run.console.log 2>&1 # launch in the background
(Proven game-omni invocation: --provider mmgw --thinking low --sandbox local, template
<piflow>/.piflow/game-omni/template, --workspace <game-omni> --out <game-omni>/out/<id>.)out/<id>/.pi/{run.json,state.json} + per-node
out/<id>/.pi/nodes/<node>/{events.jsonl,io.json,node.json}; produced artifacts land under out/<id>/
(e.g. spec/*.json). Watch with piflow status <out/<id>> / piflow watch <out/<id>> / piflow logs, or
tail a node's events.jsonl. Confirm liveness by the artifact on disk + the VCS/file evidence, never a
self-report.--from / --until)A needle matches a stage by substring against its phase, node-id, or node label (stageMatches in
@piflow/core). Two rules that bite:
--until w2-scaffold (the node id) matches;
--until "W2 Scaffold" matches NOTHING when stage.phase is unset → the window silently runs to the END.--until X runs through the LAST stage containing X; --from X resumes AT X (reusing upstream artifacts
via a stat preflight). --only X = both.A template may declare named run PROFILES in its meta.json (profiles + defaultProfile); each ELIDES a
subset of nodes so one workflow has several run shapes — e.g. a full production flow with verify gates and a
dev companion flow that elides them (docs/design/profiles-and-resume-robustness.md). Selecting one is the
whole job, and it is short:
meta.json profiles keys) — those are the ONLY valid names; never invent one.--profile <name>: "just build it / dev run / skip the gates" →
the gate-eliding profile (e.g. companion); "full / unattended / validated" → the default (e.g.
production); a profile they name → use it. No flag → the template's defaultProfile. An unknown name
ERRORS loudly, listing the declared ones (a typo can't silently run the wrong shape).--from/--until still window WITHIN it.When a profile elides the verify gates, the orchestrator IS the verifier — judge each node's artifact
against the criteria fixture as it lands (piflow-enhance / hermes-skill-system's node-validation loop).
(Obsolete: hand-windowing gates out with --until <last producer> — use --profile; it rewires deps so a
--from resume never blocks on an elided gate's missing artifact, the failure that motivated this.)
events.jsonl: explore-forever /
in-head work / a missing input the prompt needed. Fix at the node's SKILL or the seed, not by re-running.--thinking low — the CLI now forwards it to pi --thinking, but if you OMIT it pi defaults to
medium and over-thinks (the #1 cause of a slow/never-finishing node). The -e node-contract extension
(the write-first gate) is still not auto-passed by the SDK CLI — note that as an enhancement target; do not
fake around it.run post-hook non-zero) → the deterministic step (gen / seed-contract /
merge) failed: check the hook cmd path resolves under {{WORKSPACE}} and {project}, and its exit/stderr.RunOptions knobs, headless invariants) live in
piflow-init's reference/observability.md + reference/provider-and-headless.md — read them when a run
misbehaves; do not duplicate them here.npx claudepluginhub blueif16/piflowCreates bite-sized, testable implementation plans from specs or requirements, with file structure and task decomposition. Activates before coding multi-step tasks.