piflow-init

name

piflow-init

description

Pi Flow · INIT — create a structured workflow (a DAG of producer/verify nodes coordinating through the filesystem) and stand it up to run as a fleet of efficient pi agents (pi.dev / earendil-works/pi) driven by non-Claude coding-plan models, with Claude Code as the single console. The source of truth is a structured workflow TEMPLATE (`.piflow/<wf>/template/`); the `@piflow/core` SDK loads it into a WorkflowSpec and runs it one `pi` per node. INIT triages your starting point — PORT an existing Claude `.js`, IMPORT another engine's workflow (n8n/YAML/JSON), or COMPOSE fresh — then builds the template and the per-repo runner. Use to "create/author a pi-flow workflow", "stand up the runner in a repo", "port my Claude workflow to pi", "import an n8n workflow", "run my workflow on a non-Claude model", "pi-runner". To RUN/monitor an existing workflow use piflow-start; to IMPROVE one use piflow-enhance.

Pi Flow · init — create & stand up a structured workflow on a pi fleet

One-line model: the structured workflow template (.piflow/<wf>/template/) is the single source of truth; the @piflow/core SDK loads it into a WorkflowSpec and runs it, one efficient pi process per node, while Claude Code owns the graph and monitors the run. A Claude Code Workflow .js is an OPTIONAL one-time INGEST seed — init lifts it into a template, then it is discarded. One authored template: no codegen, no hand-sync, no drift, no second source.

init ──(PORT a .js ONCE │ IMPORT n8n/YAML │ COMPOSE fresh)──► .piflow/<wf>/template/   ← the SOURCE OF TRUTH
                                                                    │ @piflow/core: loadTemplate → WorkflowSpec → compile → runWorkflow
                                                                    ▼ one `pi` per node (non-Claude coding-plan model)
   .piflow/<wf>/runs/<id>/{ product · .pi/state.json · .pi/nodes/<id>/io.json } ──► `piflowctl logs`   ← piflow-start owns this

The three Pi Flow skills (this is the lifecycle)

Skill	Role	Status
piflow-init (you are here)	CREATE a workflow: triage the source → build the template/ → stand up the per-repo runner	full
piflow-enhance	IMPROVE a running workflow: the capture→route→edit→verify loop, the criteria fixture, Companion Mode judging	stub (scope declared)
piflow-start	RUN & monitor a workflow on the pi fleet: dry-run → live → piflowctl logs	stub (scope declared)

Paths below are relative to the piflow repo root (~/Desktop/piflow). This skill lives at .claude/skills/piflow-init/; references like reference/sdk-consumer.md, docs/design/template-format.md, templates/pi-runner/, and packages/core are at that repo root.

Step 0 — triage your starting point (do this FIRST)

Getting a workflow into the template has a few distinct conditions, each with its own method. Match exactly one row, then route. If none matches, STOP and say so — do not hand-roll an unsupported intake; that is how a silent, wrong workflow gets built.

You have…	Condition	Method
A proven Claude Code Workflow .js (agent()/parallel()/pipeline()/phase())	PORT	references/parse-claude-workflow.md + scripts/parse-claude-workflow.mjs — extractWorkflow runs it under recording stubs and captures the EXACT realized prompts + DAG; you author the rest (tools/mcp/contract-as-data/hooks/refs). ✅ implemented
A workflow in another engine's format (n8n / YAML / JSON)	IMPORT	Map the foreign graph → the template's DAG manifest + per-node defs. ⛔ not yet — do not improvise; stop and flag the missing importer
Only a task/goal, or a skill/agent system described in prose	COMPOSE	The agent REASONS the task into a DAG — START from a blueprint shape (references/blueprints/; the composition grammar is references/blueprints/AUTHORING-GUIDE.md) and stamp/insert it with the scaffold loop (below), each lane bound to a base agent via --agent-type. ✅

• Before authoring a lane's prose, run the skill-marketplace ladder — references/skill-marketplace.md. A node's craft belongs in a SKILL, not its prompt.md, so first SEARCH for one that already carries it (piflowctl skill list/search --json, then the remote lane), INSTALL it if remote (piflowctl skill add), and BIND it (add-node --skill <id>) — reach for an existing bundle before hand-writing craft. No match ⇒ compose the node without a skill; NEVER invent a skill id.

• The PORT script is the bridge; its 0 exit is the oracle. It ends by compile()ing its own output and asserting the DAG survived — trust the exit code, not a glance at the JSON. A non-zero exit means the spec is not trustworthy; fix the cause named in the error, never hand-edit around it.

• Mechanical port = the floor, not the finish. references/parse-claude-workflow.md names what the script CANNOT recover (data-flow reads, hooks, the contract decisions) and how to refine it. Read that before you ship the template.

• PORT = TRANSLATE the source's INTENT into our idioms; never transcribe its STRUCTURE. The source graph (Claude .js / LangGraph) is a spec of intent, not a shape to mirror — a step that was a graph node THERE is not automatically a pi node HERE. Understand our functionality FIRST, then map each step to its MOST NATIVE construct: an agentic step → a pi node; a deterministic step that STAGES a file the model reads → a PRE-hook seed; a deterministic step that RUNS a fetch or ESTABLISHES shared state → an upstream programmatic node + promote; a human pause → a checkpoint; a QA/fix loop → rerouteTo/--from; a build/test gate → an op gate. The #1 port smell — a pi node whose whole prompt is "run X and return its output" — is a pass-through the source happened to model as a node; it MUST become a hook or a programmatic node, NEVER a pi. You are re-expressing the workflow in our SDK, not adding nodes.

• New conditions are a new row + a new reference + (if programmatic) a new script — never more prose here.

• The scaffold loop IS the convenience pathway — author by flags, never by hand-writing node JSON. Stamp any template (COMPOSE, or extend a PORT) with the CLI: → per node (config is emitted from flags, re-runnable as a deterministic function of them; the FULL gate/judge/checkpoint/control surface is flags too — see the gate-authoring bullet below) → each (the PROSE — the only part that's yours) → to TEST (free DAG preview, no model — the real loadTemplate gate). binds a whole base agent (its tools + skill + the OBSERVABLE label, via the real ) in one flag; binds ONE resolvable skill by its bare id → (an explicit OVERRIDES the preset's fallback ; the id resolves through the skill rings at run time — find/install it first with the marketplace ladder, ). This is how a node is scaffolded or customized in a single line — reach for it before hand-authoring, and after every change to confirm the DAG still compiles.

The per-run shape (designed, partially confident — not a separate "store" to build). There is no database/registry layer: the TEMPLATE itself (.piflow/<wf>/template/, D8) is the canonical source — authored once here, customized per workflow. Each run is a DUPLICATION of it: init-RUN (init(${RUN}), D7/D9) instantiates a thread by materializing ${RUN}/.pi/ and copying each node's per-node configs (prompt.md · tools · mcp · node.json) into ${RUN}/.pi/nodes/<id>/, then filling the runtime STATE on top (state.json channels + the io.json ledger). So a run = a regenerable instance of the template (template COMMITTED; runs/<id>/ GITIGNORED). This is the canon's two inits distinction — init-TEMPLATE (authoring, THIS skill) vs init-RUN (runtime instantiation). The shape is specified in docs/design/sdk-canonical-build-plan.md (D7 per-run .pi/ layout · D8 source-of-truth · D9 .piflow/ namespaces) + docs/design/template-format.md §10, and partially landed (U6a); the template loader + init-RUN (U6b–U8) are the remaining build, with open naming nits (.pi/ vs _meta/). INIT today is PORT + COMPOSE (the scaffold loop + blueprints); IMPORT is still deferred. Do not finalize the template format or those open per-run items here.

Standing up the project (after the template exists)

The engine is the @piflow/core package; a project does NOT copy an engine, it installs the package and drops in a thin consumer. The canonical per-project layout, the file→mission map, and the full adopt steps are in reference/sdk-consumer.md — read it first. The flow:

1. Confirm the source of truth — the template. The workflow lives as a structured template at .piflow/<wf>/template/ (DAG manifest + per-node defs as data + refs — see docs/design/template-format.md), built by Step 0's triage. You edit the TEMPLATE; there is no maintained .js, no second source, no copy. (Today's PI_RUNNER_WORKFLOW still points at a .js pending the loader — the migration target is the template dir; see docs/design/sdk-canonical-build-plan.md D8.)

2. Set the credential ONCE in pi's global config (per machine, not per repo). The model + key live in pi's native ~/.pi/agent/models.json, which pi resolves for EVERY project — so no product needs its own key or .env credential. cp templates/models.json.example ~/.pi/agent/models.json, edit apiKey/baseUrl/model ids, chmod 600, verify pi --list-models cp. See reference/provider-and-headless.md.

3. Install @piflow/core + drop in templates/pi-runner/. Copy the folder next to .claude/, set the @piflow/core dependency in pi-runner/package.json (a file: path to this repo's packages/core, a workspace dep, or the published package), and npm install. The sdk/ glue + hooks/ op engine are the byte-identical generic consumer — you edit none of them; per-repo specifics live in .env + package.json + your hooks/. See reference/sdk-consumer.md.

4. Configure the per-repo wiring .env (wiring only, no secret). cp .env.example pi-runner/.env; set PI_RUNNER_WORKFLOW (the .js path, repo-root relative), PI_RUNNER_ROOT if pi-runner/'s parent isn't the repo root, and PI_RUNNER_PROVIDER/PI_RUNNER_MODEL (or leave the provider default). Optional: PI_RUNNER_NODE_TIMEOUT, , , .

Opt-in hardening (each is one switch + its reference — read before arming):

• Output Contract — wrap each producing node with contract({ artifacts, owns, readScope }) (templates/workflow-snippets/contract.js) so the driver verifies REQUIRED artifacts independent of the self-report. The read-scope is authored at the SAME time as the writes. reference/artifact-contract.md.
• Write isolation for fleets — WorktreeSandboxProvider (--worktree): each run in its own git worktree. reference/worktree-isolation.md.
• OS read-scope — SeatbeltSandboxProvider (--sandbox, macOS): a node's readScope becomes a kernel-enforced deny-all-reads-except. reference/read-scope-sandbox.md.
• Escalation gate — on a verified failure, consult a stronger cross-family model once (reference/escalation.md; engine-baked in the monolith, consumer-side + deferred under the SDK).
• The criteria fixture — standing up a workflow seeds <repo>/.agents/skill-system-criteria.md, the per-node human-judged quality bar (NEVER injected into a prompt). Maintained by hermes-skill-system (the improve loop — see piflow-enhance).
• Claude Code executor (per-node, OPTIONAL) — a node may run on a headless local Claude Code session instead of a pi: author --executor claude-code on piflowctl add-node (or "executor":"claude-code" in node.json), and map its Claude-side tier models with piflowctl model set <tier> <id> --claude (aliases opus|sonnet|haiku or full claude-* ids). The credential is a ONE-TIME, freely-SKIPPABLE step: piflowctl claude-code connect persists a claude setup-token to ~/.piflow/claude-code.json (chmod 600). Skip it on macOS — an existing claude login (keychain) is used automatically; the file is the portable layer for Linux/cloud. The runner resolves the token host-side (env → that file → local login) and strips ANTHROPIC_API_KEY so a stray key never silently bills the API. Absent on a node ⇒ pi, byte-identical to today. docs/design/agent-executor-interface.md.

The laws (do not violate)

• Single source of truth = the structured template. Improve a wave by editing its node def / its skill in the template (.piflow/<wf>/template/); the engine loads the change automatically. The Claude .js is an init-only INGEST seed, discarded after — NEVER a maintained second source. Zero hand-sync.
• The engine is the @piflow/core package, not a per-repo copy. The generic consumer glue (sdk/, hooks/, extract.mjs, logs.mjs) stays byte-identical across repos — 100% of per-repo specifics live in .env + package.json (wiring) + your hooks/ (your ops), and the credential lives once in pi's global ~/.pi/agent/models.json. An engine fix is a package bump, not a manual merge; a glue fix is a one-file copy. If you find yourself editing the consumer glue for one repo, you're re-introducing the drift this whole pattern exists to prevent — push it into .env/package.json/hooks/ instead. (The Tier-2 glue still ships in the template only because @piflow/core has named gaps; it is slated to graduate into the package — see reference/sdk-consumer.md.)
• Ingest once, then author — not codegen, not a live bridge. To PORT an existing Claude .js, extractWorkflow runs it under recording stubs and captures the exact prompts + DAG ONCE; init maps that into the template, and the .js is discarded. Thereafter the engine loads the TEMPLATE directly (loadTemplate → WorkflowSpec). There is no two-way bridge and no Claude-Workflow execution target — pi + the human + the verify harness are the proving ground.
• Driver owns the graph; pi owns the node. Plain code decides stage order + parallel lanes + halt-on-failure; the model never decides control flow. Nodes coordinate via the filesystem.
• The workflow orchestrates; the SKILL carries the craft — never duplicate craft into a node body. When a node loads a skill (SKILL TO LOAD AND FOLLOW: …), split content by OWNER. The workflow .js holds ORCHESTRATION ONLY: the node sequence + parallel lanes (the DAG), each node's I/O contract (contract({artifacts,owns,readScope}) + the return schema), and a THIN wiring body — who the node is · which input artifacts it reads · which output it writes · the load-and-follow pointer. The CRAFT — to do the work: the method, the bar, the build path, the domain detail — lives ONLY in the skill, its single canonical home. A node body that RESTATES the skill's craft is two ground truths: every craft edit then needs two edits and they drift (the dual-maintenance trap). So put all craft in the skill, keep the body a pointer, and Extraction is unchanged — the realized prompt is still the (thin) body, and the model reads the loaded skill at runtime; only WHERE the craft text lives collapses to one home. (Inline-prompt nodes with no backing skill are exempt — there the body IS the only home; this law governs the skill-backed pattern.)

Run profiles (product-declared modes) — let the USER choose how many

A workflow can declare named run PROFILES in its template meta.json — each a GENERIC node-ELISION predicate the SDK applies before compile (docs/design/profiles-and-resume-robustness.md). A profile that elides the verify/gate phase yields a producing-only DAG (the dev-time "companion" posture, where the orchestrator IS the verifier); the default runs everything (the unattended "production" posture). The names are the PRODUCT's vocabulary, declared as DATA — @piflow/core carries none of it (it knows only "elide the nodes this predicate matches, rewiring deps so the survivor graph is gateless").

• Authoring a workflow that has gate/verify nodes? PRESENT THE USER A CHOICE of how many profiles to declare — and ONE is a fine, common answer. Don't force a pair. Offer, Claude-Code style: (1) just one default profile [recommended if unsure]; (2) add a dev profile that elides the gate nodes (faster babysat runs); (3) more, you name them. Declare the chosen set as profiles + defaultProfile in meta.json:

  "profiles": { "production": {}, "companion": { "elidePhases": ["verify-1", "verify-2"] } },
  "defaultProfile": "production"
  

  A profile selects nodes to elide by their generic phase tag — so give the gate nodes a shared phase. Selecting one at run time is --profile <name> (piflow-start owns that).
• A profile may only elide nodes that CREATE NOTHING — that IS the verify-node law above. Drop the gates and every key artifact still exists, because PRODUCERS made them; that is precisely why the gate phase is safely elidable. A verify node that is also a producer can't be elided — split it FIRST.
• When the gates are elided, the orchestrator IS the verifier. Run in the background; the moment a node goes ok, judge its artifact against (a) the GOLD sample and (b) its criteria-fixture entry — the dual reference the hermes-skill-system node-validation loop uses (criteria stay a JUDGING reference, NEVER injected). You cover every surface the elided gates would have.
• On a heavy mistake, stop — don't pour effort onto a bad upstream artifact. Fix at the canonical owner (Hermes), rerun the SUFFIX from the first changed node (), reuse unchanged upstream. Borderline → surface to the human (the eye). Promote a fresh artifact over the gold when it's better. A dev-time POSTURE on a product-declared profile — no engine branch, no per-workflow code. Pairs with the criteria fixture and 's node-validation loop.

Designing a node's I/O — the standards + the I/O map

Designing a workflow IS setting each node's input/output standards — this is the most meaningful place to fix them, and where an edit must be reconciled against the rest. For every node:

• One node, one task, so its I/O is a clean boundary; split a two-job node. A producer creates each key artifact; a verifier never does (the verify-node law above).

• Format the output for its CONSUMER, not by default. Strict typed JSON ONLY at a machine boundary (a parser / schema / the driver). PROSE/Markdown for an LLM-reasoning hand-off (a middle product the next model THINKS over): reason-in-prose, structure LAST — strict JSON on a reasoning hand-off taxes reasoning ~5–15% and ~35% tokens, worst on non-Claude models, and inverts CoT when a decision field precedes its rationale. Push the schema boundary as LATE as possible; keep a small fenced-JSON tail only for the fields a parser reads. Merge/denormalize for a single downstream reasoner; split only for parallel agents. (Full prompt-craft + citations: agentic-prompt-design §5.)

• Declare two things at node-creation time: the contract({ artifacts, owns, readScope }) (what it WRITES

  • its read surface) AND the artifact's CONSUMERS in the I/O map.

• Split MECHANICAL from INTELLIGENT, then push the mechanical into a DRIVER HOOK — don't leave it to the model. List the node's steps; for each ask: "is this output a fixed function of already-frozen on-disk inputs, with no judgment?" YES → a deterministic driver hook (a Hook in hooks/, run by runHooks, not the model) — so it becomes a TESTED CODE PATH, not a per-run gamble. Two verbs, one family: a PRE-hook (DRIVER-SEED) STAGES inputs before the model (copy a skeleton/tree → FILL-don't-COMPOSE); a POST-hook (DRIVER-PROJECT/DRIVER-MERGE) DERIVES/validates outputs after the model (project a frozen spec → its runtime data file, merge fragments, schema-check). NO (design reasoning / open-ended coding / prose authoring / diagnose-and-fix) → the model. Declare the deterministic part as DATA in the registry, so the engine stays uniform + genre-agnostic. Why: it removes the non-Claude-model explore-forever / mis-project thrash surface, makes mechanical output un-hallucinatable, and cuts tokens. The hook envelope + the DRIVER-marker → Hook assembly: reference/sdk-consumer.md; the marker spec: reference/artifact-contract.md. Marker-grammar law: skeleton guide prose must be quote-safe for edit anchors — never a bare single-word bracket token (, ) in a placeholder, since some model gateways mangle it inside a tool-call argument string as XML; the colon-bearing sentinel is the proven-safe convention. Canonical home: (the marker grammar).

The node I/O map — <repo>/.agents/skill-system-io-map.md, the THIRD standing artifact beside the skill-system map (composition) and the criteria fixture (quality). It is the producer→consumer ledger keyed by ARTIFACT: for each on-disk artifact, which node PRODUCES it, which nodes CONSUME it, and HOW (strict parse vs LLM read — because that is a format change's blast radius). Derive it once from the node read-lines; update it on the SAME trigger as the map. Before changing a node's output, read the artifact's consumer row and reconcile every one; after, verify no consumer reads the stale shape.

Files in the piflow repo (paths relative to the repo root, ~/Desktop/piflow)

• reference/sdk-consumer.md — READ FIRST to stand up a project. The canonical per-project layout (the three tiers + the file→mission map), the adopt steps, and the pre/post hook-assembly contract.
• reference/observability.md — piflowctl logs (docker-logs for a run): the run-status + event-archive contract, the CLI (-f/--summary/--node/--raw), the pre-run tool audit, the RunOptions knobs, and the failure-signature table. Read (with piflow-start) when a run misbehaves.
• reference/cli.md — the run flags + the --from/--until/--only node-range model + the .env knobs. Applies to sdk/run.mjs (some monolith-only flags are legacy). Read so node ranges are never guessed.
• reference/architecture.md — why the workflow runs unchanged: the invariants + the one dynamic-workflow caveat. Read to understand the pattern.
• reference/artifact-contract.md — the Output Contract + the DRIVER-* marker grammar (the authoring surface for hooks + the write/read contract). Read to make a node deliver the right artifact + to author a hook.
• reference/escalation.md — the escalation gate (engine-baked in the monolith; consumer-side + DEFERRED under the SDK). Read before arming escalation.
• reference/orchestration.md — Claude-Code-as-console: dry-run → background live → poll. Read to operate a run (piflow-start).
• reference/worktree-isolation.md — WorktreeSandboxProvider physical write-isolation for fleets. Read before a --worktree fleet.
• reference/read-scope-sandbox.md — SeatbeltSandboxProvider OS read-scope (macOS): the DRIVER-READ-SCOPE marker + the full-runtime-surface grants. Read before --sandbox.
• reference/provider-and-headless.md — the native ~/.pi/agent/models.json credential + the headless invariants/watchdog. Read for setup + when a node hangs.

Reference implementation

The worked instance is game-omni: its .claude/workflows/game-omni-v1.6.js is the INGEST SEED being ported into a .piflow/game-omni/template/ (the extractWorkflow → init path); pi-runner/sdk/ runs @piflow/core on the in-place LocalSandboxProvider with hooks/ bound in. The original battle-tested monolith lives in the animation-test repo (lesson-build → 14 nodes / 10 stages, matching templates/legacy/run.mjs) — the pre-SDK reference. When in doubt, those repos are the worked examples.