# yoke-pi ```mermaid flowchart LR grill --> task grill-docs --> prd task --> plan --> do --> review --> gca --> gp --> pr handoff help ``` **yoke-pi** is a pi.dev package of workflow skills adapted from yoke. The migration is incremental: a small set of skills is pi-native today, and the rest are explicitly marked as deprecated / pi-port pending until they are rewritten. ## Installation Install the interactive question helper first: ```bash pi install npm:pi-ask-user ``` Install yoke-pi from GitHub: ```bash pi install git:github.com/yokeloop/yoke-pi pi ``` For a pinned release: ```bash pi install git:github.com/yokeloop/yoke-pi@v0.0.2 ``` After npm publication, installation will be: ```bash pi install npm:yoke-pi ``` For local development from this repository: ```bash pi install -l . pi ``` After installing or editing skills in a running pi session, use: ```text /reload ``` Check that it works: ```text /skill:help ``` ## Skill status | Command | Status | What it does | | ------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `/skill:gca` | ✅ pi-adapted | Git staging and commit with smart file grouping. | | `/skill:grill` | ✅ pi-adapted | Interviews the user one interactive question at a time about a plan or design; every question offers a recommended answer. | | `/skill:grill-docs` | ✅ pi-adapted | Same as grill, plus maintains the domain glossary (`CONTEXT.md`) and ADRs in `docs/adr/`. | | `/skill:handoff` | ✅ pi-adapted | Compacts the current conversation into a handoff document for a fresh agent. | | `/skill:help` | ✅ pi-adapted | Explains how to use yoke-pi and lists skill status. | | `/skill:gp` | ✅ pi-adapted | Git push with checks and report. | | `/skill:gst` | ✅ pi-adapted | Shows development status: branch, changes, commits, hot files, summary. | | `/skill:issues` | ✅ pi-adapted | Breaks a plan/PRD into vertical-slice GitHub issues and saves a local index. | | `/skill:prd` | ✅ pi-adapted | Turns conversation context into a PRD and optional GitHub issue. | | `/skill:bootstrap` | ⚠️ deprecated: port pending | Prepares a project for the yoke flow. Still contains Claude-specific instructions. | | `/skill:do` | ⚠️ deprecated: port pending | Executes a task per plan. Still depends on Claude-style sub-agent orchestration. | | `/skill:explore` | ⚠️ deprecated: port pending | Codebase exploration and brainstorming. Needs pi-native `ask_user` and subagent replacement. | | `/skill:fix` | ⚠️ deprecated: port pending | Quick fix or follow-up change. Still contains Claude-specific paths/hooks. | | `/skill:plan` | ⚠️ deprecated: port pending | Builds an implementation plan from a task file. Still depends on Claude-style sub-agent orchestration. | | `/skill:pr` | ⚠️ deprecated: port pending | Creates or updates a GitHub Pull Request. Needs pi-native body generation and package-local script/path adaptation. | | `/skill:review` | ⚠️ deprecated: port pending | Finds problems in code, fixes them, and produces a report. Still depends on Claude-style sub-agent orchestration. | | `/skill:sync-docs` | ⚠️ deprecated: port pending | Regenerates docs/catalog. Still targets the old Claude-oriented catalog surfaces. | | `/skill:task` | ⚠️ deprecated: port pending | Drafts a task file for AI implementation. Still depends on Claude-style sub-agent orchestration. | Pending skills have `disable-model-invocation: true` in their frontmatter so pi should not auto-select them. They can still be invoked explicitly while porting. ## Pi-adapted skills ### `/skill:grill` Read-only interactive design grilling. Uses `ask_user` one question at a time, always with a recommended answer first. ```text /skill:grill should we cache sessions in Redis or Postgres ``` ### `/skill:grill-docs` The same interview loop, plus inline maintenance of: - `CONTEXT.md` — domain glossary - `docs/adr/NNNN-*.md` — architecture decision records ```text /skill:grill-docs design the order cancellation flow ``` ### `/skill:handoff` Writes a concise handoff document to the OS temp directory and prints its absolute path. ```text /skill:handoff continue porting yoke to pi ``` ### `/skill:gca` Classifies the git working tree and creates atomic commits with English Conventional Commit messages. ```text /skill:gca /skill:gca #86 ``` ### `/skill:help` Shows pi-specific yoke guidance and the current port status. ```text /skill:help ``` ### `/skill:gst` Shows repository status with branch, changed files, commits, stash, and summary. ```text /skill:gst ``` ### `/skill:gp` Pushes the current branch to `origin` with checks and a report. ```text /skill:gp /skill:gp --force-with-lease ``` ### `/skill:prd` Synthesizes current context into a PRD artifact and optionally publishes it as a GitHub issue. ```text /skill:prd ``` ### `/skill:issues` Breaks a PRD, plan, spec, or current context into vertical-slice GitHub issues. ```text /skill:issues docs/ai/my-feature/my-feature-prd.md ``` ## Repo-local maintainer skills The repository also versions pi project-local maintainer skills under `.pi/skills/`: | Command | Purpose | | ---------------------- | ----------------------------------------------------------- | | `/skill:yoke-create` | Create or port yoke-pi skills and their docs. | | `/skill:yoke-release` | Release yoke-pi using `package.json` as the version source. | | `/skill:yoke-validate` | Validate changed skills/docs for pi compatibility. | | `/skill:journal` | Append concrete session changes to `journal.md`. | These are hidden from automatic invocation with `disable-model-invocation: true` and should be invoked explicitly while working in this repository. ## Repository structure ```text .pi/skills/ # Versioned repo-local maintainer skills for pi skills/ # Shipped Agent Skills discovered by pi skills/*/SKILL.md # Skill definitions skills/*/reference/ # Skill-local references skills/*/agents/ # Legacy Claude-style agents; pi port pending lib/ # Helper scripts; several still need package-path adaptation site/ # Astro/Starlight documentation site docs/ # Reference docs and migration notes AGENTS.md # pi-facing project instructions CLAUDE.md # legacy migration context; not the pi source of truth .claude*/ hooks/ # legacy Claude Code files kept during soft cleanup ``` ## Migration policy - New pi-facing docs and skills use `/skill:`, not `/yoke:`. - Interactive decisions use `ask_user` from `pi-ask-user`. - New project instructions target `AGENTS.md`. - Claude Code files remain temporarily for soft cleanup, but are legacy and should not receive new functionality. - Port pending skills should stay hidden from model auto-invocation until rewritten. ## Development ```bash pnpm install pnpm run format pnpm run format:check ```