Pocket help

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:

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:

{
  "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-correction · 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 · pocket-init · create-pr	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 (pocket-init and pocket-help are the exceptions — standalone setup/routing helpers). 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. create-pr is the Pocket Enterprise PR recorder (see below).

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
pocket-review returned REVIEW_FAIL — fix and re-record	pocket-correction	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
New/existing repo needs Pocket set up (CLAUDE.md, enterprise)	pocket-init	standalone
Enterprise phase done — open the linked PR	create-pr	standalone (enterprise)

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 (REVIEW_FAIL?)
   │  pocket-correction      USER triggers on REVIEW_FAIL · sequential fixes · append-only corrections [CORRECTIONS_RECORDED]
   ▼ (re-run pocket-review)
reviews written (all pass)
   │  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 on passing runs (closing owns that). On PHASE_BLOCKED (preflight failure) it stops with the preflight failure message. On any REVIEW_FAIL it does not chain; it prints an Action Required block pointing to pocket-correction. On REVIEW_BLOCKED it halts — resolve the escalation before re-reviewing.
• pocket-correction is the REVIEW_FAIL fix stage (user-triggered). It delegates each failed task's fix to an implementer subagent (main agent stays Delegator + Auditor), records an append-only correction commit via pocketto-pi log update --correction (done_sha never moves), and hands back for user-triggered re-review. Corrections are SEQUENTIAL — never parallel.
• 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 — follow pocket-review's Action Required block before re-reviewing.

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

Pocket Enterprise (opt-in team layer)

The pipeline above is local-first. With Pocket Enterprise enabled (/pocketto:pocket-init or pocketto-pi mode init), the same stages also leave a GitHub trace — nothing else changes:

• pocket-grinding → creates a GitHub issue from the approved spec (summary + full spec in a collapsible section).
• pocket-development → offers /pocketto:create-pr at PHASE_COMPLETE and syncs a task-checklist comment to the issue.
• create-pr → opens the phase PR on the current branch, linked to the issue (refs/closes).
• pocket-review → posts verdicts as a PR summary comment + inline findings (reconciled, no duplicates).
• pocket-closing → posts the closeout comment to the issue; with require_approval: true it blocks the close until the PR is APPROVED. Pocket never merges PRs or closes issues — humans do.

Detection is fail-closed: without a valid ## Pocket Enterprise block in AGENTS.md/CLAUDE.md, every skill behaves exactly as local mode with zero GitHub calls.

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