\n\n# piflow\n\n
![\"npm\"](\"https://img.shields.io/npm/v/%40arche-sh%2Fpiflow?style=flat-square\")
\n
![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/arche-sh/piflow/ci.yml?style=flat-square&label=CI\")
\n
![\"license\"](\"https://img.shields.io/npm/l/%40arche-sh%2Fpiflow?style=flat-square\")
\n
![\"Node]()
=22.19\" src=\"https://img.shields.io/badge/node-%3E%3D22.19-339933?style=flat-square&logo=node.js&logoColor=white\" />\n\n**English** | [한국어](README.ko.md)\n\n**Debugging, planning, and repo-resume loops for pi.**\n\nType `debug this` and your agent runs a real diagnosis loop — reproduce,\nminimize, fix, regression-test — instead of guessing. piflow packages that\nloop, plus a dozen more, as installable skills for\n[pi](https://pi.dev), a minimal terminal coding harness.\n\n
![\"Real](\"docs/demos/diagnose.gif\")
\n\n[Install](#install) · [First win](#first-win) · [Demos](#demos) · [Start here](#start-here) · [Skills](#skill-bundle) · [Runtime](#runtime-layer) · [Develop](#develop)\n\n
\n\n\n> *“what did I work on here last, and what should I do next?”* loads **`where`**\n\n![\"Real](\"docs/demos/where.gif\") \n\n**Resume cold.** Rebuilds the work map from git + sessions, then ends on two grounded next-work plans.\n\n |
\n\n\n> *“break this checkout plan into tickets we can grab independently”* loads **`to-tickets`**\n\n![\"Real](\"docs/demos/to-issues.gif\") \n\n**Split the work.** Turns a loose plan into independent tracer-bullet vertical slices, each grabbable on its own.\n\n |
\n\n\n> *“let's build slugify test-first, red-green-refactor”* loads **`tdd`**\n\n![\"Real](\"docs/demos/tdd.gif\") \n\n**Build a slice.** Writes the failing tests first, then implements until red turns green.\n\n |
\n\n\n> *“let's prototype this rate limiter and try a few designs”* loads **`prototype`**\n\n![\"Real](\"docs/demos/prototype.gif\") \n\n**Explore a fuzzy design.** Builds a throwaway, runnable app so the shape can be judged before committing.\n\n |
\n
\n\n---\n\n## Install\n\n```bash\npi install npm:@arche-sh/piflow\npi\n```\n\nNeeds `python3` on PATH. `/where` and `/taste` read your session history with\nbundled Python scripts, and without an interpreter those two skills fail\nrather than degrade. `piflow doctor` tells you if it is missing.\n\n### First win\n\nOpen pi inside a repo where you have worked before, then paste:\n\n```text\n/where\n```\n\npiflow asks the session-mining role for a compact state map: what changed,\nwhat mattered, and two plausible next-work plans. You do not have to rebuild\nthe whole thread from memory.\n\n---\n\n## Start here\n\nPick by the question you are actually holding, not by skill name:\n\n| Your situation | Entry | Why this one |\n|---|---|---|\n| Reopening a repo — \"where was I?\" | `/where` | Mines your past pi sessions into resumable work threads instead of you rebuilding the thread from memory |\n| Something is broken / failing / slow | `debug this` | Loads `diagnosing-bugs`: reproduce → minimize → hypothesize → instrument → fix → regression-test, instead of guess-and-edit |\n| You can't decide by talking — \"how should it look/behave?\" | `/prototype` | A cheap concrete artifact creates the decision; words alone won't |\n| You can decide by talking — \"A or B?\" | `/grill-with-docs` | One question at a time until decisions are spent; CONTEXT.md and ADRs update as they land |\n| The discussion is done — freeze it | `/to-spec` | Synthesizes the conversation into a spec on the tracker, no re-interview |\n| A plan needs to become work items | `/to-tickets` | Tracer-bullet tickets with blocking edges — each grabbable on its own |\n| Tickets/spec exist — build it | `/implement` | Drives `/tdd` at agreed seams, closes with `/code-review`, commits |\n| Huge and foggy — \"I don't even know what I don't know\" | `/wayfinder` | Charts a shared map of decision tickets; resolves them one per session until the way is clear |\n\n**The daily loop** is the middle rows: `/where` → (an amplifier if uncertain:\n`/prototype` or `/grill-with-docs`) → `/to-spec` → `/to-tickets` → `/implement`.\nThe back half flows on its own — the only real choice you make is the amplifier.\n\nSlash commands load a contract deterministically; plain English (\"debug this\",\n\"prototype this first\") works when it matches a skill's trigger, so name the\nskill whenever you already know the stage you're in.\n\n---\n\n## Skill bundle\n\nEach skill is a pre-flight checklist for one kind of question. Grouped by the\nquestion they answer:\n\n