--- slug: "pocketto-pi" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/rfxlamia/pocketto@main/README.md" repo: "https://github.com/rfxlamia/pocketto" source_file: "README.md" branch: "main" ---
# πŸͺ Pocketto **Structured AI coding workflows for [Claude Code](https://docs.claude.com/en/docs/claude-code) and [Pi](https://github.com/badlogic/pi-mono).** From a rough idea to reviewed, shipped code β€” without the agent improvising. [![npm](https://img.shields.io/npm/v/pocketto-pi?color=cb3837&logo=npm)](https://www.npmjs.com/package/pocketto-pi) [![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-d97757)](https://docs.claude.com/en/docs/claude-code) [![Node](https://img.shields.io/badge/node-%E2%89%A518-3c873a?logo=node.js&logoColor=white)](https://nodejs.org) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](#license)
--- ## Why Pocketto? Coding agents are great at *writing* code and bad at *not skipping steps*. Pocketto adds the missing discipline: - **Plan before code.** Specs, acceptance criteria, and TDD-structured plans come before a single line is written. - **Delegate with contracts.** Every subagent gets a "Pocket Packet" β€” objective, verification, stop conditions. No packet, no spawn. - **Gate before done.** Reviews and a hard close step keep finished work from rotting in `IN_PROGRESS` limbo. 15 skills, one namespace, zero lock-in β€” reach for the full pipeline on real features, or grab a standalone skill for everyday work. Working in a team? Opt into [Pocket Enterprise](#pocket-enterprise-opt-in) and the same pipeline tracks itself on GitHub β€” issues, PRs, and review verdicts.

The Pocket pipeline: pitching β†’ grinding β†’ planning β†’ structuring β†’ development β†’ review β†’ closing, plus standalone skills (pocket-help, bug-hunting, hotfix, brand-design, structured-research)

## Install
PiClaude Code
```bash pi install git:github.com/rfxlamia/pocketto # or pi install npm:pocketto-pi ``` ```bash /plugin marketplace add rfxlamia/pocketto /plugin install pocketto@pocketto /reload-plugins ```
### Pi extensions (Pi users) Pocket's skills call Pi extensions for their core features β€” **advisor** (review gates), **context7** (library docs), and **subagents** (delegation). After installing, pull them in with one command: ```bash npx pocketto-pi setup-extensions # required extensions npx pocketto-pi setup-extensions --all # + recommended extensions npx pocketto-pi doctor # check what's installed / missing ``` | Required | Unlocks | |----------|---------| | `pi-mcp-adapter` | context7 MCP β€” library-aware code generation | | `@gotgenes/pi-subagents` | subagent delegation + parallel reviews | | `@juicesharp/rpiv-advisor` | advisor β€” LLM-to-LLM review/escalation gates | Recommended (install with `--all`): `@juicesharp/rpiv-ask-user-question`, `@tintinweb/pi-tasks`, `@aliou/pi-processes`. > **New here?** Start with [`pocket-help`](#standalone-skills) β€” a compact router that explains what Pocket is and which skill to reach for, without loading every skill into context. ## Quickstart Run a feature through the full pipeline β€” each stage hands off to the next: ```bash /pocketto:pocket-grinding "add dark mode toggle" # β†’ spec + acceptance criteria /pocketto:pocket-planning # β†’ TDD execution plan /pocketto:pocket-development # β†’ subagents build it, task by task /pocketto:pocket-review # β†’ parallel reviewers gate the work /pocketto:pocket-closing # β†’ reconcile, close, summarize ``` Or just fix something: ```bash /pocketto:bug-hunting "checkout total is off by one cent" /pocketto:hotfix "bump the rate-limit window to 60s" ``` ## The 15 skills ### Pipeline (chained) Each stage invokes the next at handoff, carrying spec, plan, and acceptance criteria forward. Use these for real features and non-trivial work. | # | Skill | When to reach for it | |---|-------|----------------------| | 1 | `pocket-pitching` | Rough idea, no clear problem yet | | 2 | `pocket-grinding` | Clear problem β€” need a spec + acceptance criteria | | 3 | `pocket-planning` | Spec ready β€” need an execution plan | | 4 | `pocket-structuring` | Plan ready β€” passthrough ≀6 tasks, phase-split β‰₯7 | | 5 | `pocket-development` | Plan ready β€” execute task-by-task via subagents | | 6 | `pocket-review` | After a phase/plan is DONE (user-triggered) | | 7 | `pocket-correction` | After pocket-review returns REVIEW_FAIL (user-triggered) | | 8 | `pocket-closing` | After reviews pass β€” gate, close, summarize | ### Standalone skills Lighter, single-purpose, no pipeline. Reach for these for everyday work. | Skill | When to reach for it | |-------|----------------------| | `pocket-help` | "What is Pocket?", which skill to use, how the flow works | | `pocket-init` | Onboard an existing project: generate CLAUDE.md/AGENTS.md, enable enterprise | | `bug-hunting` | Fix a bug, debug a failure, audit code for hidden bugs | | `hotfix` | Small-to-medium change where the full pipeline is overkill | | `brand-design` | Design system, creative brief, brand identity, UI tokens | | `structured-research` | Validate an explicit assumption before it enters planning | | `create-pr` | Open the phase PR linked to the Pocket issue (enterprise mode) |
πŸ“– Full skill reference β€” what each skill actually does
**`pocket-pitching`** β€” Pre-grinding problem exploration. Use **before** `pocket-grinding` when the problem is unformed. Guides divergeβ†’converge with structured brainstorming and LLM-to-LLM curation, then produces a pitch exploration doc. *Trigger:* "pitch this", "explore this idea", "I have a rough idea". **`pocket-grinding`** β€” BDD-driven feature/fix discovery before any implementation. Use when planning a feature, designing a fix, or exploring options. Invokes `pocket-planning` at handoff. *Trigger:* "pocket-grinding", "brainstorm", "think through", "plan this", "before we build". **`pocket-planning`** β€” Converts a `pocket-grinding` spec into a TDD-structured execution plan of full Pocket Packets. Outputs tasks ready to dispatch via `pocket-development`. *Trigger:* "create plan", "build plan", or invoked by `pocket-grinding`. **`pocket-structuring`** β€” Splits a `pocket-planning` plan into sequential phase files. Passthrough below 7 tasks, phase-split at β‰₯7. Produces phase files for `pocket-development`, one at a time. *Trigger:* "structure plan", "split plan", or invoked by `pocket-planning`. **`pocket-development`** β€” Precise subagent delegation for task-by-task execution. Every delegation requires a Pocket Packet β€” a structured contract with objective, verification criteria, and stop conditions. Enforces 6 iron laws: no packet = no spawn. *Trigger:* "execute plan", "delegate tasks", "dispatch subagents". **`pocket-review`** β€” Post-phase batch reviewer. **User-triggered** after `pocket-development` marks a phase/plan DONE β€” it does NOT auto-call. Dispatches parallel reviewer subagents (one per task), each covering spec compliance and code quality, then writes results to `reviews/`. On `REVIEW_FAIL`, prints Action Required pointing to `pocket-correction`. On `REVIEW_PASS` for all tasks, auto-chains to `pocket-closing` after one confirmation. Returns `PHASE_REVIEWED` or `PHASE_BLOCKED`. *Trigger:* `/pocketto:pocket-review `. **`pocket-correction`** β€” REVIEW_FAIL fix stage. **User-triggered** after pocket-review reports `REVIEW_FAIL`. Main agent stays Delegator + Auditor β€” it never writes code. Reads `fix_instructions` from each `REVIEW_FAIL` review, delegates fixes to implementer subagents **sequentially** (never parallel β€” parallel collapses commits, corrupting per-task file attribution), runs a quick audit per task, then records the fix commit append-only via `pocketto-pi log update --correction` (`done_sha` never moves). Does NOT auto-invoke re-review β€” emits a handoff message instead. Returns `CORRECTIONS_RECORDED`, `CORRECTION_PARTIAL`, `NOTHING_TO_CORRECT`, or `CORRECTION_BLOCKED`. *Trigger:* `/pocketto:pocket-correction /`. **`pocket-closing`** β€” Terminal stage. **User-triggered** after `pocket-review` writes verdicts. Reconciles every `reviews/*.json` against `log.json`, gates the close on verdicts (any fail or unreviewed task β†’ `CLOSE_BLOCKED`), advances passed phases `REVIEW β†’ DONE`, runs `log close`, and writes `closeout.md`. Returns `CLOSED`, `PHASE_ADVANCED`, `CLOSE_BLOCKED`, or `ALREADY_CLOSED`. *Trigger:* `/pocketto:pocket-closing `. **`bug-hunting`** β€” Systematic debugging with confirmed root cause before any fix. Reactive (fix known bug) and proactive (hunt hidden bugs) modes. Enforces: claim β‰  evidence β‰  root cause β‰  fix. *Trigger:* "fix bug", "debug", "why is X broken", or proactive code review. **`hotfix`** β€” Fast iteration for small-to-medium changes. Enforces brief-plan + subagent-review gates before implementation β€” accuracy without full pipeline ceremony. *Trigger:* "quick fix", "small change", "just update X". **`brand-design`** β€” Brand-aware design system generator that acts as Head of Brand. Translates abstract brand language into a mathematically-validated, implementation-ready design system, writes `creative-brief.md` as the source of truth for all UI/UX, and can compile it to framework tokens (Tailwind v4 `@theme`, v3 preset, or plain CSS custom properties). *Trigger:* "brand-design", "design system", "creative brief", "brand identity", "set up UI tokens", "export design tokens". *Deliverables:* `docs/pocket/rule/creative-brief.md`, `creative-brief-preview.html`, `.claude/rules/brand-design.md`, optional generated token file (`brand.theme.css` / `tailwind.brand.preset.js` / `tokens.css`). **`pocket-help`** β€” Compact onboarding and routing guide for the whole system. Explains what Pocket is, when it beats lighter flows, and which skill to invoke β€” without loading every skill into context. *Trigger:* "what is pocket", "how do I use pocket", "which pocket skill", "pocket-help". **`pocket-init`** β€” Onboards an existing (brownfield) project onto Pocket. Scans the codebase and writes an evidence-based project memory file (`CLAUDE.md` on Claude Code, `AGENTS.md` on Pi) in a merge-safe managed section, then optionally enables Pocket Enterprise (`pocketto-pi mode init`) and scaffolds GitHub issue/PR templates (`pocketto-pi scaffold github`). Enterprise stays strictly opt-in. *Trigger:* "pocket-init", "set up pocket", "onboard this project", "generate CLAUDE.md", "enable enterprise mode". **`create-pr`** β€” Pocket Enterprise recorder that opens (or reuses) the GitHub PR for a completed development phase on the **current branch** β€” it never manages branches. Commits traveling state (`log.json` + plan/spec docs), formats a structured What/Why/How-to-Test body linked to the Pocket issue (`refs`/`closes`), and records the PR in `.pocket-meta.json`. Requires enterprise mode. *Trigger:* "create-pr", "open a PR", or offered by `pocket-development` after a phase completes in enterprise mode. **`structured-research`** β€” Validates an explicit assumption before it leaks into planning or code. Operationalizes the belief into a falsifiable question, recommends a research methodology (non-binding) from a catalog of techniques, gathers cited evidence, then returns a graded verdict β€” Confirmed / Refuted / Inconclusive β€” with an advisory recommendation. *Trigger:* "structured-research", "validate this assumption", "is it true that", "research whether", "verify my assumption". *Deliverables:* `docs/pocket/research/-/research-report.md`.
## Pocket Enterprise (opt-in) Pocket is local-first β€” everything above works with zero GitHub coupling. **Pocket Enterprise** is the opt-in team layer: the same pipeline, but every stage leaves a trace on GitHub so the team can follow progress without opening your filesystem. | Stage | What enterprise mode adds | |-------|---------------------------| | `pocket-init` | One-time setup: enables the mode, scaffolds `.github/` issue + PR templates, creates the `pocket-plan` label | | `pocket-grinding` | Creates a GitHub issue from the approved spec β€” structured summary plus the **full spec** in a collapsible section | | `pocket-development` | Offers `/pocketto:create-pr` when a phase completes; syncs a live task checklist comment to the issue | | `create-pr` | Opens the phase PR on the current branch, linked to the issue (`refs`/`closes`), with traveling state committed | | `pocket-review` | Posts per-task verdicts as a PR summary comment + inline findings, reconciled across re-runs (no duplicates) | | `pocket-closing` | Posts the closeout comment to the issue; with `require_approval: true`, blocks the close until the PR is APPROVED | **Enable it:** run `/pocketto:pocket-init` (guided), or directly: ```bash npx pocketto-pi mode init --enterprise true --branch-strategy branch --create-pr true ``` This writes a `## Pocket Enterprise` block into `AGENTS.md` (or `CLAUDE.md` via `--file CLAUDE.md`) plus a `.gitattributes` for LF-normalized traveling state. Requirements: a git remote and an authenticated [`gh` CLI](https://cli.github.com). Design guarantees: - **Opt-in & fail-closed** β€” without the config block (or on any mode error), no skill ever calls GitHub; the workflow is byte-identical to local mode. - **One-way sync** β€” GitHub is the output, your repo stays the source of truth. - **Human gates stay human** β€” Pocket never merges PRs and never closes issues; the issue closes when a supervisor merges the final PR (`closes #N`). ## CLI The pocket skills drive a single cross-platform Node CLI, run via `npx` β€” no install, PATH setup, or Python required. Works the same on Windows, macOS, and Linux. Requires Node.js β‰₯ 18. | Command | What it does | |---------|--------------| | `npx pocketto-pi structure [--dry-run]` | Split a plan into phase files (passthrough if < 7 tasks) | | `npx pocketto-pi log init ` | Initialize `log.json` for a plan directory | | `npx pocketto-pi log update [--task TN] [--sha ] [--allow-duplicate-sha]` | Update phase or task status | | `npx pocketto-pi log close ` | Finalize log after all phases complete | | `npx pocketto-pi doctor [--strict]` | Check required/recommended Pi extensions | | `npx pocketto-pi mode []` | Report Pocket Enterprise mode (from `AGENTS.md`/`CLAUDE.md`) | | `npx pocketto-pi mode init [--file CLAUDE.md] …` | Write the enterprise config block + `.gitattributes` | | `npx pocketto-pi meta get\|set [value]` | Read/write `.pocket-meta.json` (issue/PR linkage) | | `npx pocketto-pi format --input ` | Render GitHub bodies to a temp file (`--body-file` safe) | | `npx pocketto-pi format tasklist ` | Render the issue task-checklist comment from `log.json` | | `npx pocketto-pi scaffold github [--dry-run]` | Write `.github/` issue + PR templates (idempotent) | | `npx pocketto-pi reconcile --prior --new ` | Set-diff review findings for PR thread upserts | Status flow: `WAITING` β†’ `REVIEW` β†’ `DONE` \| `BLOCKED` Add `--json` for a stable output envelope β€” `{ ok, command, cliVersion, contract, data, error }` β€” that skills parse instead of scraping text. Add `--contract ` for a version handshake that fails loudly on mismatch rather than emitting output an older skill can't read. ## License [MIT](https://github.com/rfxlamia/pocketto/tree/HEAD/LICENSE) Β© [rfxlamia](https://github.com/rfxlamia)