piflow-enhance

Pi Flow · enhance — improve a running workflow · STUB

This is a scope-declaring stub, not the finished skill. The canonical improvement method already exists — it is the hermes-skill-system skill (capture → route → edit → verify → human-approve → commit → record). This skill exists so the lifecycle has a clean IMPROVE entry; do NOT hand-roll a parallel method here. Load hermes-skill-system and follow it; this stub only pins the piflow-specific bindings below. (Paths are relative to the piflow repo root, ~/Desktop/piflow.)

What this skill will own (the IMPROVE half of the lifecycle)

A workflow is a living system; a flaw, a recurring finding, or user feedback on a run is a trigger to evolve it. The piflow-specific precedence rules (the part hermes doesn't know):

• Improve a wave by editing its SKILL; improve the chain (ordering, hand-offs, wiring) by editing the workflow / the template. This is the one global precedence rule (see piflow-init → "The laws" → the workflow orchestrates, the SKILL carries the craft). Corollary: NEVER restate SKILL craft in a node body — the body is a thin wiring pointer; craft lives ONLY in the skill (two grounds drift).
• One canonical home, smallest durable edit. Patch a section > add a references/ file > new skill.
• Generalize or don't ship. Every edit must hold for ALL future runs — never hard-code one case, never write a reward-hackable test.
• Anti-reward-hack is absolute. Assert OBSERVABLE state only; the oracle (assertions / the criteria fixture / the verify harness) is immutable — a fix changes real behavior, never the test.
• Reconcile consumers on any output edit (piflow-init → "The laws" → the node I/O map): change what a node writes → find every reader and re-point it, then grep the old shape clean.
• The human is the eye for the playable/observable artifact; verification is confirmed by a real run, never assumed.

The standing artifacts this skill maintains

• <repo>/.agents/skill-system-criteria.md — the per-node, human-judged QUALITY bar (the criteria fixture). Complement to the mechanical Output Contract: the contract checks the artifact exists; the criteria say whether it is good. Never injected into a node prompt (that teaches-to-the-test and voids the clean-room signal) — it is a JUDGING reference only.
• <repo>/.agents/skill-system-map.md (composition) + <repo>/.agents/skill-system-io-map.md (the producer→consumer ledger) — keep these CURRENT; a stale map is the real failure mode.

Companion Mode is the dev-time face of enhance

When you're babysitting a run, the orchestrator + human ARE the verifier: judge every stage's artifact vs the GOLD sample + its criteria-fixture entry as it lands, fix at the canonical owner, rerun the suffix. Full procedure: piflow-init → "Companion Mode (dev-time)".

Where the material is (read these — do not duplicate them here)

• hermes-skill-system skill — the canonical capture→route→edit→verify→approve→commit loop + the node-validation loop (references/node-validation-loop.md). This is the method; load it first.
• piflow-init → "The laws" + "Designing a node's I/O" — the piflow precedence + the I/O-map reconciliation rule.
• docs/design/ (this repo) — the design canon, when an improvement is an architectural change not a wave edit.

When this stub is filled in

Lift the piflow-specific precedence + the criteria/map maintenance into a self-contained skill here that composes hermes-skill-system (don't fork its method). Until then: load hermes-skill-system, apply the precedence above, and the human approves before anything lands.