yoke-pi

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:

pi install npm:pi-ask-user

Install yoke-pi from GitHub:

pi install git:github.com/yokeloop/yoke-pi
pi

For a pinned release:

pi install git:github.com/yokeloop/[email protected]

After npm publication, installation will be:

pi install npm:yoke-pi

For local development from this repository:

pi install -l .
pi

After installing or editing skills in a running pi session, use:

/reload

Check that it works:

/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.

/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

/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.

/skill:handoff continue porting yoke to pi

/skill:gca

Classifies the git working tree and creates atomic commits with English Conventional Commit messages.

/skill:gca
/skill:gca #86

/skill:help

Shows pi-specific yoke guidance and the current port status.

/skill:help

/skill:gst

Shows repository status with branch, changed files, commits, stash, and summary.

/skill:gst

/skill:gp

Pushes the current branch to origin with checks and a report.

/skill:gp
/skill:gp --force-with-lease

/skill:prd

Synthesizes current context into a PRD artifact and optionally publishes it as a GitHub issue.

/skill:prd

/skill:issues

Breaks a PRD, plan, spec, or current context into vertical-slice GitHub issues.

/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

.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:<name>, not /yoke:<name>.
• 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

pnpm install
pnpm run format
pnpm run format:check