@fernado03/pi-flow

Pi Flow

Pi Flow is a dependency-free workflow package for Oh My Pi. It packages focused engineering disciplines, command wrappers, and one tiny toggle extension (/pi-flow on|off|status) that lets you opt in or out of Pi Flow workflow preference per session.

Canonical Package

This repository root (@fernado03/pi-flow) is the canonical OMP package. It is installed via OMP and discovered statically (skills, commands, rules) plus one small runtime extension for the session toggle. There is no install hook and no executable.

Original Pi compatibility export: A separate generated export of the original Pi (badlogic/pi-mono@9b3a205, 2026-07-22) lives in compat/pi/. It installs via pi install npm:@fernado03/pi-flow, pi install <path>, or pi -e <path> (original Pi CLI), provides pi.skills adapters and pi.prompts /pi-* wrappers, and records compatibility against badlogic/pi-mono@9b3a205. It is not the canonical package. See compat/pi/README.md for boundaries, translation limits, and generator behavior.

Install (Canonical OMP Package)

Install the published package:

omp plugin install @fernado03/pi-flow

For local development, link the package directory:

omp plugin link <path>

For example: omp plugin link C:/Users/Fernado/Desktop/Projects/Code/pi-flow.

Then reload discovered plugins in the current OMP session:

/reload-plugins

Update

Update the installed package to the latest published version:

/pi-update

or directly:

omp plugin install @fernado03/pi-flow@latest --force

Then reload discovered plugins in the current OMP session with /reload-plugins. If the install fails with ConnectionRefused downloading package manifest, a registry= override in ~/.npmrc, the project .npmrc, or bunfig.toml points at an unreachable registry — comment it out and retry against the default npm registry.

Static OMP Discovery

OMP discovers this package directly from its conventional roots:

• skills/<name>/SKILL.md contains one flat skill per directory.
• commands/*.md provides slash-command wrappers.
• rules/ contains small always-loaded guidance.
• extensions/index.ts registers /pi-flow on|off|status.

There is no install hook or executable. After installing or linking, update the package files and run /reload-plugins to refresh discovery.

Activation

Pi Flow is a preference, not an override. It is on by default in every session; the bundled extension registers one command to control it:

/pi-flow on             Prefer Pi Flow workflows this session
/pi-flow off            Return to normal OMP skill selection this session
/pi-flow status         Show the current mode and configured default
/pi-flow default <on|off>  Persist the default for all future sessions

Saying stop pi flow (or normal mode) in chat also disables it for the session. The resolved default follows PI_FLOW_DEFAULT_MODE environment variable, then the persisted config file (pi-flow/config.json under your platform config directory, written by /pi-flow default), then built-in on.

While on, the extension appends a short per-turn preference (~60 tokens): choose at most one matching Pi Flow skill, skip ceremony for trivial requests, and verify observable behavior. OMP task subagents created from the session inherit the parent's preference while preserving their own system prompt. A headless or unrelated session resolves its own default independently. The session state persists across resume/branch; an explicit /pi-flow off wins over the configured default for that session tree. A status-line chip (Pi Flow: on|off) shows the current mode.

Commands

Use a wrapper in chat, for example /pi-research to investigate a decision, /pi-fix to diagnose and repair a defect, or /pi-code-review to review a focused change. The available wrappers are:

Workflow	Wrappers
Investigate and decide	/pi-ask, /pi-research, /pi-wayfinder, /pi-explore, /pi-questionnaire, /pi-to-spec, /pi-to-tickets
Build and improve	/pi-feature, /pi-fix, /pi-implement, /pi-implement-spec, /pi-prototype, /pi-refactor, /pi-tdd, /pi-tweak
Review and verify	/pi-code-review, /pi-grill, /pi-batch-grill, /pi-grill-with-docs, /pi-verify, /pi-triage, /pi-diagnose
Practice and design	/pi-improve-architecture, /pi-retro, /pi-teach, /pi-writing-for-agents
Package maintenance	/pi-update

Each wrapper routes to exactly one skill. Read a skill directly when you need its full procedure through skill://<skill-name>.

Token Strategy

The baseline prompt receives only the tiny rule content and visible skill metadata. Full skill bodies load on demand through skill:// references. User-invoked workflows set disable-model-invocation: true, keeping their metadata out of the baseline; reusable model-invoked disciplines remain visible. When /pi-flow on is active, one short preference block (~60 tokens) is appended per turn; when off, nothing is injected. This keeps ordinary turns small without discarding the detailed procedure when it is needed.

Package Checks

npm run check
npm run pack:check

check validates the static package shape, metadata budgets, command-to-skill references, and unsupported platform terminology. pack:check previews the npm tarball without publishing.

Testing

Run the test suite with:

npm test

npm test invokes scripts/test.js, which runs Bun (bun test) — the same runtime Oh My Pi already requires (packageManager: bun@1.3.x). No devDependency is added because Bun natively executes the TypeScript extension (extensions/index.ts) with no transpiler. The launcher prints a clear error when Bun is missing or older than 1.x.

License

Original Pi Compatibility Export

This repository also publishes a compatibility export of the original Pi (badlogic/pi-mono@9b3a205, 2026-07-22) under compat/pi/. It is not the canonical OMP package.

• Canonical OMP package: @fernado03/pi-flow (this repository root). Install with omp plugin install @fernado03/pi-flow.
• Compatibility export: compat/pi/ — generated adapters/wrappers for original Pi. Install with pi install npm:@fernado03/pi-flow, pi install <path>, or pi -e <path> (original Pi CLI).

What the compat export provides

• pi.skills/ — Generated adapters that reference the canonical skill bodies from @fernado03/pi-flow by relative path. No skill bodies are duplicated.
• pi.prompts/ — /pi-* slash-command wrappers that locate the installed package root and read the matching skill adapter, using original Pi's $ARGUMENTS convention.
• No runtime extension, no install hook, no executable — same static OMP package model as the canonical package.

What the compat export does NOT provide

• Not original Pi — Original Pi has no OMP plugin install/link, no rules system, no built-in task agents, and no skill:// loader.
• No bundled subagents — Original Pi's optional subagent extension is not included. Subagent-style work runs directly/sequentially unless you install that extension separately.
• No duplication — Adapters reference canonical bodies; no sync drift.

Translation boundaries

Original Pi concept	Compat export translation
task / Task (subagent)	Direct/sequential work; subagents require original Pi's optional subagent extension (not bundled)
ask	Conversational question
lsp	Language-aware navigation/compiler checks or targeted read/bash
todo	Markdown checklist
glob / grep	Targeted glob/grep/bash search
browser	Installed browser extension or manual scenario
skill://<name>	Load named installed skill (canonical body)
$ARGUMENTS (prompt args)	Preserved in pi.prompts wrappers

Generator & check behavior (deterministic, checkable)

• Generator reads canonical skills/<name>/SKILL.md and commands/*.md, emits pi.skills/<name>/SKILL.md adapters and pi.prompts/pi-*.md wrappers.
• Check verifies every adapter's canonical-skill target exists, every wrapper's target skill exists, and manifest matches canonical skill/command set.
• Fails on drift (added/removed/renamed skills or commands without regeneration).

See compat/pi/README.md for full details and CHANGELOG.md for the compatibility record against badlogic/pi-mono@9b3a205. MIT © Fernado