---
name: help
description: Explains how to use yoke and lists the available skills; also greets new users. Activated when the user writes "help", "how do I use yoke", "how to use", "what skills are available", "hi", "hello", "where do I start", or on first contact with yoke.
---

# Welcome to yoke for pi

**yoke** is a workflow skill pack for pi.dev: explore → grill → task → plan → do → review → commit → push → PR.

In pi, yoke skills are invoked as `/skill:<name>` commands.

## Quick start

```text
/skill:help
/skill:grill should we cache sessions in Redis or Postgres
/skill:gca
/skill:handoff next session should continue the pi migration
```

For the full yoke pipeline, use:

```text
/skill:explore <topic>                # explore the codebase
/skill:grill <plan>                   # stress-test the idea, read-only
/skill:grill-docs <plan>              # stress-test and capture glossary/ADRs
/skill:prd                            # PRD → GitHub issue, optional
/skill:issues                         # break into implementation issues, optional
/skill:task <ticket or description>   # formulate the task
/skill:plan <path to task file>       # build the plan
/skill:do <path to plan file>         # execute the plan
/skill:fix <description>              # quick fix after /do
/skill:review <slug>                  # prepare review
/skill:gca                            # commit with smart grouping
/skill:gp                             # push to remote
/skill:pr                             # create pull request
```

## Currently pi-adapted skills

### /skill:grill — interactive plan grilling

Interrogates you about a plan or design one question at a time with pi's `ask_user` tool. Every question offers a recommended answer first. Read-only.

**Input:** plan or topic → **Output:** shared understanding, no files

```text
/skill:grill should we cache sessions in Redis or Postgres
```

### /skill:grill-docs — grilling with domain docs

Same grilling flow, plus it maintains the glossary `CONTEXT.md` and ADRs in `docs/adr/` inline as decisions land.

**Input:** plan or topic → **Output:** `CONTEXT.md` + `docs/adr/NNNN-*.md` when needed

```text
/skill:grill-docs design the order cancellation flow
```

### /skill:handoff — conversation handoff

Compacts the conversation into a handoff document for a fresh agent, referencing existing artifacts. Saves to the OS temp directory.

**Input:** optional focus → **Output:** handoff doc in the OS temp directory

```text
/skill:handoff continue porting yoke to pi
```

### /skill:gca — git commit with smart grouping

Analyzes changed files, classifies them into groups, and creates atomic commits with Conventional Commits in English. Determines the ticket ID from the input, branch, or yoke artifacts.

**Input:** optional ticket ID, URL, slug, or artifact path → **Output:** atomic git commits

```text
/skill:gca
/skill:gca #86
```

### /skill:help — this guide

Explains the available yoke skills and the recommended flow.

### /skill:gst — repository status

Shows branch, changed files, commits, hot files, stash, and a short summary. Read-only.

```text
/skill:gst
```

### /skill:gp — git push with checks

Pushes the current branch to `origin`, reports pushed commits, and suggests PR next steps.

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

### /skill:prd — PRD from context

Synthesizes the current context into `docs/ai/<slug>/<slug>-prd.md` and can publish it as a GitHub issue.

```text
/skill:prd
```

### /skill:issues — vertical-slice issue generation

Breaks a PRD, plan, spec, or current context into independently grabbable GitHub issues.

```text
/skill:issues docs/ai/my-feature/my-feature-prd.md
```

## Other yoke skills

These skills still exist in the repository, but may require further pi adaptation before they are fully reliable:

| Skill              | Purpose                                                    |
| ------------------ | ---------------------------------------------------------- |
| `/skill:task`      | Drafts a task file for AI implementation.                  |
| `/skill:plan`      | Builds an implementation plan from a task file.            |
| `/skill:do`        | Executes a task per plan.                                  |
| `/skill:review`    | Finds problems in code, fixes them, and produces a report. |
| `/skill:fix`       | Quick fix or follow-up change.                             |
| `/skill:explore`   | Codebase exploration and brainstorming.                    |
| `/skill:pr`        | Creates or updates a GitHub Pull Request.                  |
| `/skill:bootstrap` | Prepares a project for yoke flow.                          |
| `/skill:sync-docs` | Regenerates the skill catalog docs.                        |

## Installation for pi

For local development from this repository:

```bash
pi install -l .
pi
```

Or run pi in the repository and load project skills directly once a pi package manifest is present.

Recommended companion package for interactive questions:

```bash
pi install npm:pi-ask-user
```

Then restart pi or run `/reload`.

## Notes

- pi skill commands use `/skill:<name>`, not `/yoke:<name>`.
- Interactive questions should use the `ask_user` tool when available.
- Project-level instructions live in `AGENTS.md`; `CLAUDE.md` may still be read when working in repositories that already have it.