🪐 Pocketto

Structured AI coding workflows for Claude Code and Pi. From a rough idea to reviewed, shipped code — without the agent improvising.

---

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 and the same pipeline tracks itself on GitHub — issues, PRs, and review verdicts.

Install

pi install git:github.com/rfxlamia/pocketto
# or
pi install npm:pocketto-pi

/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:

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 — 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:

/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     <plan_dir>               # → parallel reviewers gate the work
/pocketto:pocket-closing    <plan_dir>               # → reconcile, close, summarize

Or just fix something:

/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)

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 <plan_dir>.

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 <plan_dir>/<phase_file>.

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 <plan_dir>.

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/<date>-<slug>/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:

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. 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 <execution-plan.md> [--dry-run]	Split a plan into phase files (passthrough if < 7 tasks)
npx pocketto-pi log init <plan_dir>	Initialize log.json for a plan directory
npx pocketto-pi log update <plan_dir> <phase_file> <status> [--task TN] [--sha <commit>] [--allow-duplicate-sha]	Update phase or task status
npx pocketto-pi log close <plan_dir>	Finalize log after all phases complete
npx pocketto-pi doctor [--strict]	Check required/recommended Pi extensions
npx pocketto-pi mode [<dir>]	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 <dir> <field> [value]	Read/write .pocket-meta.json (issue/PR linkage)
npx pocketto-pi format <issue|pr|comment|closeout> --input <json>	Render GitHub bodies to a temp file (--body-file safe)
npx pocketto-pi format tasklist <plan_dir>	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 <json> --new <json>	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 <N> for a version handshake that fails loudly on mismatch rather than emitting output an older skill can't read.

License

MIT © rfxlamia