Skip to content
Pocketto
Pipeline

Planning

pocket-planning turns an approved spec into a TDD execution plan of full Pocket Packets, checked by a spec-reviewer subagent and a CLI dry-run.

pocket-planning bridges the grinding spec and development execution. It scans codebase context, maps file structure, decomposes acceptance criteria into TDD-structured tasks, generates Pocket Packets with test-first steps and commits, then runs a spec-reviewer subagent, plus a conditional test-strategy audit, before handoff.

Core principle: Every task is red → green → refactor → commit. Steps live inside the task. Planning owns test intent; development owns test implementation.

When to use it

  • A grinding handoff arrived (spec path + acceptance criteria).
  • You say "create plan from spec" or "build execution plan".
  • A spec exists under docs/pocket/spec/ and needs to become executable tasks.

When not to use it:

  • No completed grinding spec exists: run grinding first.
  • The task is already in execution: use development directly.

How to invoke it

/pocketto:pocket-planning

Usually invoked by grinding, or by you with the spec path.

How it works

  1. Phase 0: Preflight. Codebase scan of the affected areas (plus reusable-helper search so tasks import instead of reinventing), test-framework detection, and version-matched library docs (Context7 resolve-library-id → query-docs when available) for every dependency whose behavior affects a task.
  2. Phase 1: Parse the spec. Extract design decision, constraints, acceptance criteria, out-of-scope, open questions, rollback plan. Flag duplicate/contradictory rules and rules missing GWT.
  3. Phase 2: File structure mapping. Every rule gets exact Create / Modify / Test paths, no wildcards. Shared logic across 2+ files becomes a named, domain-scoped helper; every non-trivial implementation file gets a test file.
  4. Phase 3: Decompose. Six decomposition rules, including: one task = one bounded deliverable; steps live inside the task; scaffolding is always its own [prereq] task; cross-unit scenarios get their integration verification decided here. Tasks carry dependency annotations ([prereq], [depends: T1], [parallel: T3], [test-risk]), and the chain is walked for cycles before presentation. Plans with 10+ tasks get a recommended phase grouping.
  5. Phase 4: Generate Pocket Packets. A complete 7-field packet per task. Behavioral tasks carry test intent, not test code: test file, level, GWT intent, boundary, test doubles, expected RED reason, and the exact command, never the test's source.
  6. Phase 5: Spec reviewer. An independent subagent verifies spec coverage, usable test intent, and no placeholder failures (Approved / Issues Found / Needs Context). Bounded recovery: two materially different rounds, then RECOVERY_CHECKPOINT, never an unreviewed handoff.
  7. Phase 6: Test strategy audit (conditional, skip by default). Dispatched only when a trigger fires: cross-unit GWT scenarios, genuinely ambiguous test levels, persistence/concurrency/network behavior that changes how a task must be tested, or a [test-risk] task.
  8. Phase 7: Output and validation. The plan is saved, then dry-run validated (mandatory, non-authorizing).

Outputs and artifacts

docs/pocket/plans/YYYY-MM-DD-kebab-slug/execution-plan.md

The full document format is specified in Plan structure.

Approval gates and constraints

  • The dry-run is mandatory before any approval gate:
npx -y pocketto-pi structure "docs/pocket/plans/{date}-{slug}/execution-plan.md" --dry-run --json --contract 3

ok == false (for example NO_TASKS, UNKNOWN_TASK_REF, CYCLE_DETECTED) stops everything until the plan is fixed. On success the envelope reports data.action (single | split) and data.executionFlow (the run-order graph).

  • Plan approval ≠ implementation approval. Approving the plan authorizes generation of derived execution artifacts (index.md, task files, phase manifests). Structuring asks separately for execution authorization.
  • Edits are revalidated by tier. Cosmetic edits need only a re-run dry-run; semantic packet edits re-run the spec reviewer; test-strategy/topology edits re-run the trigger check plus the reviewer. Only a version that passed its tier may be approved.

Example

Illustrative: the JWT-refresh spec yields T1 [prereq] token-store schema, T2–T3 [parallel: T2] issue/verify endpoints, T4 [depends: T2, T3] [test-risk] rotation-on-reuse, each packet carrying its RED-cycle test intent and exact test commands.

Grinding

pocket-grinding: BDD-driven requirement discovery that turns a clear problem into an approved spec with Given/When/Then acceptance criteria.

Structuring

pocket-structuring hands decomposition to the Pocket CLI, which turns an approved execution plan into an index, per-task files, and phase manifests.

On this page

When to use itHow to invoke itHow it worksOutputs and artifactsApproval gates and constraintsExampleRelated documentation