piflow

One npm package. One pi extension. Two surfaces.

An autonomous engineering skill framework for the pi runtime — built on Matt Pocock's skills — bundled with the delegate role primitive (scout, researcher, navigator, scribe, session-miner).

pi install npm:@arche-sh/piflow

That registers piflow as a pi package source. The runtime extensions and skills are loaded from the installed package root; from here on you talk to the agent, not to a tool palette.

Do not also mirror the same piflow skills into ~/.pi/agent/skills/; that creates duplicate skill-name collisions. If you have old copied mirrors, run npx @arche-sh/piflow@latest cleanup-global-mirrors.

piflow combines the former pi-dev skills framework and pi-role delegate extension; ADR-0019 records the absorption decision.

What you get

Two pi extensions, shipped together:

• piflow-delegate — registers a single delegate tool. Hands a task to an in-process child AgentSession configured by a roles/*.md profile. Shipped roles cover codebase recon, pi-internals navigation, ADR drafting, session recall, single-provider research, cross-provider research verification, and compute-first analysis.
• piflow-guard — minimal message_end plugin that catches mid-chain follow-up: … run /do … hand-backs and queues a steer so the next turn re-enters the chain instead of waiting for the user to type "진행해" / "go".

Plus the package-managed skill set under the installed package's skills/ directory:

/do      — do the engineering work end-to-end
/taste   — view or update engineering preferences
/where   — recall prior pi sessions for this cwd
/mario   — activate the mario engineering persona for this session
/matt    — activate the matt engineering persona for this session

Behind /do sit twelve specialist skills — diagnose, tdd, to-prd, to-issues, triage, grill-with-docs, improve-codebase-architecture, zoom-out, recon-with-vision, migrate, setup, and improve-skill-flow — chained automatically based on intent (feature / bug / perf / refactor / recon / docs / triage / audit) and scope (nano / small / medium / large).

Install

Requires Node ≥ 20 and the pi runtime.

# Preferred: package-managed install. pi loads extensions + skills from the package root.
pi install npm:@arche-sh/piflow

# Local development of piflow itself: register this repo as the package source.
pi install /Users/jason/pi/piflow
# or keep an equivalent entry in ~/.pi/agent/settings.json packages.

# Verify package-managed layout and detect stale global mirrors.
npx @arche-sh/piflow@latest doctor

# Move old ~/.pi/agent/skills piflow mirrors aside when they match package skills exactly.
npx @arche-sh/piflow@latest cleanup-global-mirrors

The piflow install / piflow update commands are retained for legacy copied-resource setups and preferences seeding. When piflow is already configured as a pi package source, they skip copying skills and extensions so the package root remains the single runtime source.

Toggle the guard

~/.pi/agent/settings.json:

{
  "piflow": {
    "enabled": false
  }
}

Default: on. The legacy piFlow (camelCase) key still works as a compatibility backstop; reading it emits a single stderr deprecation line.

How /do actually flows

[ /do <your request> ]
        │
        ▼
   bootstrap → classify intent+scope → execute the matching chain
        ├─ feature × small    →  (zoom-out?) → tdd → (improve-codebase-architecture?)
        ├─ feature × large    →  zoom-out → grill-with-docs → to-prd → to-issues → triage → tdd per slice → improve-codebase-architecture
        ├─ bug × any          →  diagnose → tdd (regression) → improve-codebase-architecture
        ├─ recon × any        →  recon-with-vision → (to-prd / to-issues)
        └─ … (full table in skills/do/SKILL.md)
        ▼
   live-verify locally (agent boots and drives the stack)
        ▼
   side effects per prefs (commit, push, open PR, file issues, label)
        ▼
   one-screen final summary

The first time you run /do in a new repo, the migration gate fires:

1. /migrate normalises AGENTS.md, archives handoff systems, locks them out via .gitignore, stamps the marker.
2. /setup scaffolds docs/agents/{issue-tracker,triage-labels,domain}.md.
3. /taste auto-detects project signals, asks only where the project diverges from your global preferences, writes docs/agents/preferences.md.

After that, /do runs uninterrupted.

Preferences: three layers, last write wins

~/.pi/agent/preferences.md            # global   — your engineering taste
docs/agents/preferences.md            # project  — overrides for this repo
packages/<pkg>/preferences.md         # package  — overrides for this subtree (optional)

The keys that move the needle most:

| key | what it controls | | --- | --- | | interrupt-on-ambiguity | how willing the agent is to ask vs. pick a default and report it | | change-budget | how big a chunk a single /do run is allowed to swallow | | auto-create-issues / auto-apply-labels | whether tracker side-effects happen automatically | | auto-commit-per-slice / auto-pr | how aggressively work lands on main | | local-live-policy / ops-live-policy | when the agent boots locally vs. probes prod |

What's a skill?

A directory with a SKILL.md. That's the whole format. The pi runtime reads the directory name and the markdown frontmatter and exposes the skill as /<name>. No code, no plugin API — just instructions for the agent, version-controlled like any other prose.

Credits

The engineering discipline encoded in tdd, diagnose, to-prd, to-issues, triage, grill-with-docs, improve-codebase-architecture, zoom-out, recon-with-vision, and the setup template comes from Matt Pocock's skills repo. The vertical-slice / tracer-bullet vocabulary, the deletion test, the seam/adapter language, and the triage state machine are all his work.

This package adds:

• do — a one-shot orchestrator that picks the right chain
• migrate — a strict gate that normalises any repo into the canonical shape and probes for drift on every re-entry
• taste — three-layer preferences with project-aware onboarding
• where — pi-session recall for multi-session work
• mario / matt — explicit persona lenses that compose under the action skills instead of replacing their lifecycle gates
• delegate — the role primitive (formerly the pi-role extension)
• piflow-guard — the mid-chain hand-back steer (formerly the standalone pi-flow extension)

If these skills earn their keep for you, please support the upstream:

• Matt Pocock — https://www.mattpocock.com
• pi runtime — https://github.com/badlogic/pi

Release process

Versioning, changelog, tagging, and npm publishing are automated by release-please:

1. Land changes on main using Conventional Commits (feat:, fix:, perf:, refactor:, docs:, chore:).
2. release-please opens or updates a Release PR that bumps the version and writes CHANGELOG.md.
3. Merge the Release PR. release-please tags the commit and creates a GitHub Release.
4. The Release workflow rebuilds, retests, and runs npm publish --access public automatically.

Required one-time setup (maintainer):

• NPM_TOKEN repository secret with a granular publish token from npmjs.com (read + write, 2FA bypass enabled).
• The repo is currently private; if it becomes public, re-enable --provenance in .github/workflows/release.yml for sigstore attestation.

License

MIT.