Structuring
pocket-structuring hands decomposition to the Pocket CLI, which turns an approved execution plan into an index, per-task files, and phase manifests.
pocket-structuring is deliberately thin: the Pocket CLI does the work. It turns a completed execution plan into execution-plan/index.md, one file per task under execution-plan/tasks/, and phase manifests when the plan needs multiple phases. Parsing, decomposition, file generation, and log reconciliation are all CLI-owned; the JSON result is the source of truth.
When to use it
- After pocket-planning hands off an approved plan.
- When you ask to structure a plan directly.
When not to use it:
- The plan is already structured.
- You explicitly choose to skip it: the plan then remains flat (a legal choice; development accepts a flat source plan).
How to invoke it
npx -y pocketto-pi structure "<path-to-execution-plan.md>" --json --contract 3Parse the JSON envelope; on success it reports the feature, task and phase counts, generated paths, and whether the execution log was rebuilt. Do not infer success from prose, and do not generate these files manually.
CLI protections
| Flag | Effect |
|---|---|
| (none) | Decompose; protects existing execution progress when a changed plan would alter task topology |
--dry-run | Validate and summarize without writing anything |
--force | Rebuild topology only when there is no execution progress |
--reset | Discard progress and start a fresh execution log, never without your explicit authorization (it discards WAITING/REVIEW/DONE/BLOCKED state) |
On failure, inspect the error and plan: recoverable causes (wrong path, malformed input) are corrected and the command re-run. A contract mismatch means a compatible CLI version is needed. It is not a plan-format error. If structure was interrupted mid-write, re-run with --reset on that plan before continuing; do not hand-repair log.json.
Outputs and artifacts
execution-plan.mdis the source plan.index.mdis the task index in execution order.tasks/T1-*.mdholds one file per task.phase-N.mdexists only when the plan is multi-phase.log.jsonis created or updated bylog initorstructure.
Multi-phase manifests carry phase metadata ("Phase N of M", prerequisite, contained tasks, what it unlocks) and a ## Phase Completion Gate section development evaluates verbatim.
Approval gates and constraints
- Structuring authorizes generation of plan artifacts only, never implementation. After a successful run it continues to development only if you asked to begin execution or already authorized that handoff; otherwise it reports and stops.
- The CLI is the only writer for these files.
Related documentation
- Planning
- Development: the next stage
- Generated files
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.
Development
pocket-development runs an approved plan task by task: subagents implement under Pocket Packets, read-only reviewers audit, and each phase ends in a pass.