Generated files and directory conventions
The docs/pocket directory tree and project-level files Pocketto generates, which command writes each one, and the naming conventions to keep.
All durable Pocket artifacts live under docs/pocket/. Names are conventions the skills and CLI rely on. Keep them.
The tree
| Path | Written by |
|---|---|
spec/<date>-<slug>/pitch-exploration.md | pocket-pitching |
spec/<date>-<slug>/<topic>.md | pocket-grinding (the spec) |
plans/<date>-<slug>/ | Same slug as the spec, easy cross-reference |
execution-plan.md | pocket-planning |
execution-plan/index.md | structure CLI (task index, execution order) |
execution-plan/tasks/T1-*.md | structure CLI (one file per task) |
execution-plan/phase-N.md | structure CLI (multi-phase plans only) |
log.json | log CLI (the only writer) |
reviews/<task_id>-review.json | In-loop auditor (per-task verdict) |
reviews/phase-pass-<phase_key>.json | Phase-level pass record |
reviews/phase-notes-<phase_key>.json | Durable phase handoff notes |
closeout.md | pocket-closing (append-only journal) |
research/<date>-<slug>/research-report.md | structured-research |
rule/creative-brief.md | brand-design (plus .claude/rules/brand-design.md) |
learning/<date>-<slug>.md | pocket-education (journal, when enabled) |
Project-root files:
| File | Purpose |
|---|---|
CLAUDE.md / AGENTS.md | Project guide + Education block (see Configuration) |
.pocket-meta.json | meta CLI; Enterprise remote identity |
.pocket/lifecycle-adapter.json | Enterprise install (the adapter registration) |
lifecycle.json | Committed with the spec directory (lifecycle CLI) |
.github/ | scaffold github: issue and PR templates, local |
Conventions that matter
- Slug pairing. Spec and plan share the same
<date>-<slug>directory name:create-pr, reconciliation, and lifecycle identity resolve through it. - Execution order, not task ID.
index.md's Task Index renders in phase-group (execution) order, the same orderlog initseeds dispatch state, so plans authored out of numeric sequence dispatch as written. - Canonical phase identity.
phase_key = phase-${order}comes fromlog.json, never from a filename; closeout markers (<!-- pocket-closeout:phase-${order} -->) use the same key. - Reviews live beside the plan. Per-task verdicts, phase-pass records, and phase notes are all under
<plan_dir>/reviews/, artifact-only state, no hidden side channels.
Ownership and recovery
The CLI is the only writer of log.json and lifecycle state. Skills run commands; nobody edits state files by hand. If structure was interrupted mid-write, re-run structure --reset on that plan (explicit, discards execution state) rather than repairing files manually. --force only rebuilds when there is no execution progress; --dry-run previews without writing. See Troubleshooting.
Git-ignored artifacts produce a warning: events reference artifacts by SHA-256, and a missing or changed artifact is terminal STALE_ARTIFACT at delivery.
Related documentation
- Execution artifacts: who writes what, when
- Lifecycle state
- Configuration
Configuration
Where Pocketto keeps configuration: the project memory file, the Pocket Education block, Enterprise mode, and .pocket-meta.json. Managed blocks are CLI-owned.
Pocket Packets
The seven-field Pocket Packet every subagent dispatch requires, including objective, deliverable, quality bar, and stop conditions. No packet, no spawn.