{"id":"8f1639bc-29db-4061-9eca-034f5ab28bd4","slug":"pi-workflow-kit","kind":"skill","name":"pi-workflow-kit","summary":"Spec-driven workflow for the pi coding agent: spec graph tools, live TODO plan, and workflow skills","owner":"franndeli","repoUrl":"https://github.com/franndeli/pi-workflow-kit","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-10-29T16:09:31.000Z","addedAt":"2026-11-01T02:16:34.138Z","logoUrl":"https://avatars.githubusercontent.com/u/124245758?u=721287aa55a6d37eca8f99dccac149eeaafe6fee&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["productivity","developer-tools"],"tags":["ai-agent","coding-agent","llm","pi","pi-coding-agent","pi-extension","pi-package","spec-driven-development"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-11-01T02:24:26.577Z","sample":false,"url":"https://conduits.dev/tools/pi-workflow-kit","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# pi-workflow-kit\n\n[![npm version](https://img.shields.io/npm/v/pi-workflow-kit?logo=npm)](https://www.npmjs.com/package/pi-workflow-kit)\n[![npm downloads](https://img.shields.io/npm/dm/pi-workflow-kit)](https://www.npmjs.com/package/pi-workflow-kit)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![Pi package](https://img.shields.io/badge/pi-package-8A2BE2)](https://pi.dev/packages/pi-workflow-kit)\n[![GitHub release](https://img.shields.io/github/v/release/franndeli/pi-workflow-kit)](https://github.com/franndeli/pi-workflow-kit/releases)\n\nSpec-driven workflow for the [pi](https://pi.dev) coding agent: a **spec graph** with `spec_*` tools, a **live TODO plan** shown above the editor, and a set of **workflow skills** (brainstorming, writing specs, shipping a PR, …). Extracted from ThinkRail so it runs in plain pi — for example inside Orca terminals.\n\n## Install\n\n```sh\npi install npm:pi-workflow-kit\n```\n\nOr straight from GitHub:\n\n```sh\npi install git:github.com/franndeli/pi-workflow-kit\n```\n\nRequires a recent version of `@earendil-works/pi-coding-agent` (the package's peer dependency).\n\n## What you get\n\n### Spec graph\n\n`spec_create`, `spec_get`, `spec_update`, `spec_delete`, `spec_grep`, `spec_graph` and `spec_validate` operate on the project's frontmatter-tagged Markdown specs (goal-and-requirements, architecture, module `SPEC.md`s, task specs). The `spec-graph` skill teaches the agent the conventions.\n\nA spec is any Markdown file whose frontmatter carries an `id` and a `type`:\n\n```markdown\n---\nid: auth-module\ntype: module-design\ntitle: Authentication module\nparent: architecture\ndepends-on: [session-store]\nstatus: active\n---\n\n# Authentication module\n…\n```\n\n### TODO plan\n\n`todo_write`, `todo_add`, `todo_update`, `todo_promote`, `todo_remove`, `todo_list` and `todo_plan_summary`. The agent keeps a grouped plan for the chat and the TUI shows it above the editor with live progress.\n\n- The widget starts collapsed to one line: progress plus the step in work.\n- `Ctrl+Space` (or `Option+T` where Option sends Meta) expands it inline, up to 10 lines around the step in work, and collapses it again.\n- `/todos` opens the whole plan in a scrollable panel: arrow keys or `j`/`k` move, `PgUp`/`PgDn` page, `Enter` folds a group or shows a step's note, summary and verification, `Esc` closes.\n- Plans are stored per session in `~/.pi/agent/todos/`.\n\n### Workflow skills\n\n| Skill | Purpose |\n| --- | --- |\n| `choosing-a-workflow` | Router — picks the right workflow for new work |\n| `brainstorming` | Shape a feature or fix before implementing it |\n| `writing-specs` | Quality bar for goal, architecture and module specs |\n| `asking-user-questions` | Norms for structured questions to the user |\n| `setting-up-a-project` | Onboard a project that has no spec graph yet |\n| `importing-a-codebase` | Build the initial spec graph for existing code |\n| `starting-a-new-project` | Go from a raw idea to a specced project |\n| `shipping-a-pr` | Create, update and monitor a pull request |\n| `spec-graph` | How to read, create and validate specs |\n| `todos` | How to keep the shared plan |\n\nA short system-prompt rule makes the agent route feature and bug-fix work through `choosing-a-workflow` first.\n\nScratch files the skills write (task specs, PR bodies, screenshots) go in `.pi/context/` inside the project — add that to your `.gitignore`.\n\n## Recommended companions\n\nThe skills call these when they are installed:\n\n- [`@thinkrail/pi-ask-user-question`](https://www.npmjs.com/package/@thinkrail/pi-ask-user-question) — structured multiple-choice questions.\n- [`@thinkrail/pi-visualize`](https://www.npmjs.com/package/@thinkrail/pi-visualize) — Mermaid diagrams and comparisons in the terminal.\n\n## Project layout\n\n```\nspec-graph/   spec_* tools and the spec index\ntodos/        todo_* tools and the TUI widget\nworkflow/     system-prompt routing rule\nskills/       workflow SKILL.md files\n```\n\n## Contributing\n\nIssues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Please follow the [Code of Conduct](CODE_OF_CONDUCT.md), and report security issues as described in [SECURITY.md](SECURITY.md).\n\n## License\n\n[Apache-2.0](LICENSE). Originally part of ThinkRail.\n"}