---
name: pocket-help
description: Onboarding and routing guide for the Pocket skill ecosystem. Use when someone asks what Pocket is, which Pocket skill to use, how the end-to-end flow works, or when Pocket is better than lighter Superpowers-style flows. Trigger on "what is pocket", "how do I use pocket", "which pocket skill", "explain pocket", "pocket-help", or any onboarding/routing question. This is a compact entry point — it summarizes every skill so agents and users do NOT have to load each SKILL.md to orient.
---

# Pocket Help

The map of the Pocket ecosystem. Read this first to understand what Pocket is, pick the right skill for the moment, and run the full flow from rough idea to reviewed code — **without loading every skill into context.**

**Core principle:** Orient cheaply, then load deep. This skill is a summary and a router. Load an individual skill's `SKILL.md` only when you reach the stage that uses it. That is the whole point — it preserves the context window for the actual work.

**This skill does not replace the detailed skills.** It tells you which one to open next.

## What Pocket Is

Pocket is a set of skills for **systematic, structured development** — from a vague idea to shipped, reviewed code. Instead of one agent improvising an entire feature in a single long thread, Pocket breaks the work into bounded stages with explicit gates: explore → specify (BDD) → plan (TDD) → phase → delegate → review.

Each stage produces a concrete artifact (pitch doc → spec → execution plan → phase files → commits → review reports) that the next stage consumes. Gates between stages force confirmation before proceeding, which is what keeps a long build from drifting.

## Prerequisites — Pi extensions

On Pi, Pocket's skills call extensions for their core features. Without them, skills hit dead-ends when they try to call `advisor()`, `subagent()`, or `context7_*` tools. Install them once after installing Pocket:

```bash
npx pocketto-pi setup-extensions        # required
npx pocketto-pi setup-extensions --all  # + recommended
npx pocketto-pi doctor                  # check installed vs missing
```

| Required | Feature it powers |
|----------|-------------------|
| `pi-mcp-adapter` | context7 — library-aware code generation |
| `@gotgenes/pi-subagents` | subagent delegation + parallel reviews |
| `@juicesharp/rpiv-advisor` | advisor — LLM-to-LLM review/escalation gates |

Recommended (with `--all`): `@juicesharp/rpiv-ask-user-question`, `@tintinweb/pi-tasks`, `@aliou/pi-processes`. Claude Code users get these capabilities from the harness and do not need the Pi extensions.

### Connecting context7 (MCP)

`pi-mcp-adapter` is only the bridge — context7 itself is a hosted MCP server you register once with an API key:

1. Sign up at <https://context7.com/> and create an API key (dashboard → API Keys).
2. Add it to `~/.pi/agent/mcp.json`:

```json
{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

`pi-mcp-adapter` picks this file up automatically (it also supports `${CONTEXT7_API_KEY}` interpolation if you'd rather keep the key in an env var). The hosted server requires the key — without it the tools won't work.

**Stuck on the JSON?** Ask the agent — it can create or edit `~/.pi/agent/mcp.json` for you once you paste in your API key.

## Two Kinds of Skills

| Kind | Skills | Use for |
|------|--------|---------|
| **Chained** (`pocket-*`) | pocket-pitching · pocket-grinding · pocket-planning · pocket-structuring · pocket-development · pocket-review · pocket-closing | Real features, non-trivial work. Each stage hands off to the next, carrying spec/plan/criteria forward. |
| **Standalone** (lighter, daily use) | bug-hunting · hotfix · brand-design · structured-research · pocket-help | Everyday work that does NOT need the full pipeline. Single-purpose, no handoff chain. |

The `pocket-*` prefix marks a skill as part of the chained pipeline. `bug-hunting`, `hotfix`, `brand-design`, and `structured-research` are deliberately *not* prefixed — they stand alone and are the right, lighter choice for most day-to-day tasks.

## Router — Which Skill Right Now?

Match your situation to one skill. Open only that skill.

| Your situation | Skill | Kind |
|----------------|-------|------|
| Rough idea, no clear problem yet — need to explore | `pocket-pitching` | chained |
| Clear problem — need a spec + acceptance criteria | `pocket-grinding` | chained |
| Approved spec — need a TDD execution plan | `pocket-planning` | chained |
| Execution plan ready — sequence/phase it | `pocket-structuring` | chained |
| Plan or phase file ready — execute task-by-task | `pocket-development` | chained |
| A phase/plan is DONE — review it | `pocket-review` | chained |
| Reviews all pass — close out the plan | `pocket-closing` | chained |
| A bug, a failure, or "audit this code" | `bug-hunting` | standalone |
| Small-to-medium change, full pipeline is overkill | `hotfix` | standalone |
| Design system / brand identity / UI tokens | `brand-design` | standalone |
| An assumption to validate before it enters planning | `structured-research` | standalone |
| "What is Pocket / which skill / how does this flow?" | `pocket-help` (you are here) | standalone |

**Routing rules of thumb:**
- Don't know if the problem is even well-formed? → `pocket-pitching`.
- Problem is clear but it's a real feature? → start at `pocket-grinding`.
- It's a quick, well-understood change? → `hotfix` (not the pipeline).
- Something is broken? → `bug-hunting` (not the pipeline).
- Holding an unverified assumption? → `structured-research` (validate it before it enters planning).
- Already have an approved spec? → skip pitching/grinding, start at `pocket-planning`.

## The End-to-End Flow (chained pipeline)

```
rough idea
   │  pocket-pitching        explore → pitch doc (2–3 directions)        [user picks next]
   ▼
clear problem
   │  pocket-grinding        BDD discovery → spec + GWT acceptance       [auto-invokes planning]
   ▼
approved spec
   │  pocket-planning        TDD plan → Pocket Packets, tests designed   [validates, routes ≤6→dev · ≥7→structuring]
   ▼
execution plan
   │  pocket-structuring     ≤6 tasks: passthrough · ≥7: split to phases [hands phases one at a time]
   ▼
plan / phase file
   │  pocket-development      delegate task-by-task via subagents         [emits PHASE_COMPLETE]
   ▼
phase DONE
   │  pocket-review          USER triggers · parallel review subagents    [PHASE_REVIEWED / BLOCKED]
   ▼
reviews written
   │  pocket-closing         USER or review auto-chains · gate · log close [CLOSED / PHASE_ADVANCED / CLOSE_BLOCKED]
   ▼
plan closed (fix findings & loop phases until every phase is DONE)
```

**Handoff facts that matter (so you don't double-invoke or stall):**
- `pocket-grinding` **auto-invokes** `pocket-planning` after you approve the spec.
- `pocket-planning`, after you approve the plan, validates it with `structure --dry-run` and routes: **≤6 tasks → `pocket-development` directly**; **≥7 tasks → `pocket-structuring`**.
- `pocket-structuring` runs only for **≥7-task (split)** plans from planning: it splits them into phase files handed off **one at a time**. (Invoked directly, it also handles ≤6-task passthrough.)
- `pocket-development` does **NOT** call `pocket-review`. It emits a `PHASE_COMPLETE` handoff; **you** invoke `pocket-review` afterward.
- `pocket-review` **auto-chains** to `pocket-closing` after **one confirmation** when every task is `REVIEW_PASS` — it still does **NOT** touch `log.json` (closing owns that). On any `REVIEW_FAIL`/`REVIEW_BLOCKED` (or `PHASE_BLOCKED`) it does **not** chain; fix and re-review. You can also invoke `pocket-closing` directly.
- `pocket-pitching` does **not** auto-chain — it presents handoff options and you choose whether to start `pocket-grinding`.

> `pocket-closing` is the terminal stage: it reconciles review verdicts, advances `REVIEW → DONE`, runs `log close`, and writes a `closeout.md`. Without it a fully reviewed plan stays in `IN_PROGRESS`/`REVIEW` limbo. Any `REVIEW_FAIL`/`REVIEW_BLOCKED` or unreviewed task makes it `CLOSE_BLOCKED` — fix and re-review first.

For the flow walked stage-by-stage with a worked example and every gate, load `references/end-to-end-flow.md`.

## When Pocket Beats a Lighter Flow

If you already use Superpowers-style skills (or just let one agent code straight through), Pocket is **stronger** when the work has any of these:

- **High ambiguity** — the problem isn't crisp yet (pitching/grinding force clarity first).
- **Multi-step build** — many tasks across files/layers (planning + development bound each one).
- **BDD/TDD discipline required** — acceptance criteria and test-first are non-negotiable.
- **Subagent delegation** — work spread across implementers needs contracts, not vibes.
- **Phase gates** — long builds drift; phase boundaries are checkpoints.
- **Context preservation** — phasing + summaries stop the thread from blowing its window.
- **Auditable execution** — every task has evidence (commits, tests, review reports).

Pocket is **overkill** when the change is small and well-understood. Then:
- known bug / failure → `bug-hunting`
- quick small-to-medium change → `hotfix`
- just UI tokens / a brand → `brand-design`
- an unverified assumption to validate → `structured-research`

For the full comparison and a "which do I reach for?" decision guide, load `references/pocket-vs-superpowers.md`.

## Context Budget Guidance

This skill exists to protect your context window. Follow this order:

1. **Start here** (`pocket-help`) to orient and route.
2. **Load one skill** — the single skill for your current stage. Not the whole set.
3. **Load that skill's references on demand** — each skill lists Reference Triggers; pull a reference only when its step says to.

Reading every `pocket-*` SKILL.md up front (≈2,800 lines combined) is exactly the waste this skill prevents.

## Reference Triggers

| Reference | When to Load |
|-----------|--------------|
| `references/skill-map.md` | Need a one-block summary of each skill — what it does, its input, its output/handoff, when to use vs skip |
| `references/end-to-end-flow.md` | Need the full pipeline walked stage-by-stage with a worked example and gates |
| `references/pocket-vs-superpowers.md` | Deciding between Pocket and a lighter Superpowers-style / standalone flow |