Core architecture
What Pocketto Core contains: the pipeline, standalone skills, Education, and the pocketto-pi CLI, plus the JSON envelope and the Enterprise boundary.
Core is the local-first product: the pipeline, the standalone skills, Pocket Education, and the pocketto-pi CLI. Everything here works with no GitHub credentials, no remote, and no Enterprise installation.
Composition
- 15 skills: six chained pipeline stages and nine standalone skills, plus the optional
pocket-enterpriseadapter skill (Enterprise only). - One CLI:
pocketto-pi(Node.js ≥ 18), the only writer of execution state. See the CLI reference. - One artifact tree: specs, plans, task files, execution logs, verdicts, and closeout journals under
docs/pocket/. See Execution artifacts.
The JSON envelope and contract handshake
Skills call the CLI with --json and --contract 3. The envelope is stable:
{ "ok": true, "command": "…", "data": { "…": "…" } }
{ "ok": false, "error": { "code": "CONTRACT_MISMATCH", "message": "…" } }A skill declares the contract it was written against. A mismatch fails loudly with guidance instead of silently emitting output the skill cannot parse. Pin the CLI (npx -y pocketto-pi@<version>) or update, as the error instructs. See Compatibility.
The Enterprise command boundary
Two CLI commands are Enterprise-owned: mode (read/configure explicit Enterprise opt-in) and format (render GitHub bodies). Core installations start without their modules. They load lazily on first use, and only when the Enterprise role is installed. A Core install asking for them gets ENTERPRISE_COMMAND_UNAVAILABLE, not a crash. The boundary is declared by the surfaces.json manifest and enforced by release builds: Core roles ship with forbidden-path and forbidden-content checks (for example, Core artifacts must not contain the string "Pocket Enterprise"). See Release surfaces.
The lifecycle layer
Core's lifecycle layer is adapter-agnostic:
lifecycle.json(committed with the spec directory) is authoritative for lifecycle state, the event journal, and delivery state.log.jsonremains the detailed task-execution projection.- State commits and events are atomic: a successful transition commits state and its event together before updating the projection.
- Delivery (the optional adapter call) happens later, during a
drain, and can never undo the local commit.
Details: Lifecycle events.
What Core never does
Core does not call gh, does not create GitHub resources, does not reconcile GitHub resources, does not merge pull requests, and does not close issues. Those capabilities belong to Enterprise, or to a human. See Local-first behavior and Integration boundaries.
Related documentation
Core & Enterprise
How Pocketto splits into a local-first Core and an optional Enterprise adapter, with a hard boundary on who owns state and who touches GitHub.
Local-first behavior
Everything Pocketto Core does with no GitHub credentials, no remote, and no Enterprise install, plus the GitHub operations Core never performs.