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/yoke-pi@v0.0.2

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