piflow

Debugging, planning, and repo-resume loops for pi.

Type debug this and your agent runs a real diagnosis loop — reproduce, minimize, fix, regression-test — instead of guessing. piflow packages that loop, plus a dozen more, as installable skills for pi, a minimal terminal coding harness.

Install · First win · Demos · Start here · Skills · Runtime · Develop

See the difference

Without piflow, a high-risk prompt often turns into a long read → confident edit → uncertain test pass.

You: debug this
Agent: reads a lot → guesses a fix → edits → maybe tests → maybe forgets why

With piflow, the work starts by loading the contract for the job.

You: debug this
Agent: loads diagnose → reproduces → minimizes → instruments → fixes → regression-tests

Fewer blank-page restarts, less context flooding in the main thread, smaller diffs, and a next move you can see.

Demos

The hero above is one move: you type plain English, piflow loads the diagnose contract on its own — the purple [skill] block — and runs it to a visible result. That same move covers the rest of the loop. Each clip below is an unedited gpt-5.5 session; the italic line is what a person types, the code is the contract the model chooses. Watch the [skill] block load before any work starts.

“what did I work on here last, and what should I do next?”  loads  where

Resume cold. Rebuilds the work map from git + sessions, then ends on two grounded next-work plans.

“break this checkout plan into issues we can grab independently”  loads  to-issues

Split the work. Turns a loose plan into independent tracer-bullet vertical slices, each grabbable on its own.

“let's build slugify test-first, red-green-refactor”  loads  tdd

Build a slice. Writes the failing tests first, then implements until red turns green.

“let's prototype this rate limiter and try a few designs”  loads  prototype

Explore a fuzzy design. Builds a throwaway, runnable app so the shape can be judged before committing.

Install

pi install npm:@arche-sh/piflow
pi

First win

Open pi inside a repo where you have worked before, then paste:

/where

piflow asks the session-mining role for a compact state map: what changed, what mattered, and two plausible next-work plans. You do not have to rebuild the whole thread from memory.

Start here

1. A bug feels slippery: use diagnose

You: diagnose this failing test

The agent must reproduce first, shrink the failing surface, form a hypothesis, instrument when needed, apply the fix, and leave a regression check behind.

2. You reopened a repo cold: use /where

You: /where

piflow mines local pi session history for the repo and returns a short “where are we?” brief instead of dumping old transcripts into the chat.

3. The design is still fuzzy: use prototype

You: prototype this state machine before we commit to the implementation

The agent builds a throwaway proof so the shape can be judged before the real codebase absorbs it.

More useful prompts

• use TDD for this — enter red → green → refactor mode.
• turn this into issues — break a plan into tracker-ready slices.
• grill this with docs — challenge a plan against domain docs and ADRs.

The full skill list is in Skill bundle below.

Skill bundle

Think of each skill as a pre-flight checklist for a work type. You can invoke some directly with slash commands, and the model can load the rest when your normal-language request matches the skill description.

• /taste — view or update engineering preferences.
• /where — reconstruct repo state from pi sessions, git, and tracker context.
• /mario — use the small-primitives engineering persona.
• diagnose — reproduce → minimize → hypothesize → instrument → fix → regression-test.
• tdd — red → green → refactor through vertical slices.
• prototype — create a throwaway proof before committing to structure.
• grill-with-docs — stress-test a plan against domain docs and decisions.
• improve-codebase-architecture — find seams for testability, boundaries, and maintainability.
• zoom-out — map the code area before diving into edits.
• to-prd — turn conversation context into a product requirements document.
• to-issues — break a plan into independently grabbable implementation issues.
• triage — move issues through the documented triage state machine.
• setup-matt-pocock-skills and onboard-repo — scaffold repo context that the engineering skills depend on.
• browser-use-cli — use the browser-use CLI for visible browser work.

Several engineering workflow skills are vendored from Matt Pocock’s skill set. piflow preserves that attribution while packaging the workflow for pi — see the ADR and LICENSE.

Runtime layer

The runtime layer stays small. Each piece removes one recurring session failure mode.

• skill exposes model-invocable engineering contracts through one tool. The model chooses the skill; piflow does not rewrite the user’s prompt.
• delegate runs bounded child-agent work and returns a compact handoff. The model invokes it for you when a prompt like “map the auth flow and tell me where redirects are decided” needs a read-only codebase scout; active roles are explore and session-miner (/where recall).

Each role owns its ordered model candidates in extensions/delegate/roles/*.md. Those frontmatter lines—not README prose or an older dated benchmark—are the live routing source. A user-local role-routes.json entry strictly replaces the keyed role's entire shipped candidate list, so leave the file absent or {} when you want shipped fallbacks to remain active. See Role routes.

• tick injects a trusted local date anchor so “today” does not come from model memory.
• nudge turns a silent provider wait into a visible recovery path.
• bootstrap seeds missing support files without overwriting user-owned files and warns about older copied resources that can shadow the package.

Tune or disable the nudge watchdog when needed:

PIFLOW_NUDGE_BUDGET_MS=0 pi

// ~/.pi/agent/piflow/config.json
{
  "nudge": { "enabled": false }
}

CLI

The CLI is for package maintenance and cleanup, not the daily workflow.

npx @arche-sh/piflow help
npx @arche-sh/piflow doctor
npx @arche-sh/piflow install -y
npx @arche-sh/piflow update
npx @arche-sh/piflow cleanup-global-mirrors

Use it to seed support files, inspect package readiness, and move old copied skill mirrors aside. Daily work should feel like normal pi conversation.

Upgrading from an older copied install? The normal package path loads skills straight from the manifest, with no copied skill mirror. If this machine used an older copied install, run npx @arche-sh/piflow doctor once after installing to move the stale mirror aside.

Docs map

• CONTEXT.md — domain vocabulary and product shape.
• docs/agents/domain.md — package concepts and source-of-truth notes.
• docs/agents/triage-labels.md — issue workflow labels.
• docs/agents/patterns.md — pi extension and TUI patterns used by piflow.
• docs/role-routes.md — shipped candidate source and strict user-local route semantics.
• docs/research/README.md — current delegate-routing evidence and supersession index.
• docs/adr/ — decision records, including retired surfaces kept as history.

Develop

npm install
npm run build
npm test
npm run typecheck
npm run check

Repo rules that protect the product shape:

• skills/ is the source of truth for shipped skills.
• src/manifest.ts and skills/ stay in sync.
• delegate remains one tool; a new persona is a role profile or skill, not a surprise second delegate surface.
• TypeScript is strict ESM with .js import suffixes.
• No runtime dependencies; peer dependencies and platform APIs only.
• release-please owns versions and changelog files.

License

MIT. See LICENSE.