# Pocketto

> Pocketto `4.0.0` provides local-first AI coding workflows for Claude Code and Pi. Core is useful without GitHub or Enterprise; the optional Enterprise adapter consumes durable neutral lifecycle events and owns all remote reconciliation.

## Release surfaces

The schema-1 `surfaces.json` manifest defines exactly four roles:

- `pi/core` — local-first Core workflows for Pi.
- `pi/enterprise` — additive Enterprise adapter for Pi; requires `pi/core`.
- `claude/core` — local-first Core workflows for Claude Code.
- `claude/enterprise` — additive Enterprise adapter for Claude Code; requires `claude/core`.

Protocol versions are independent: `CONTRACT=3`, `PIPELINE=5`, `LIFECYCLE_SCHEMA=1`, `ADAPTER_CONTRACT=1`, and `SURFACE_MANIFEST=1`.

Core commits state and events locally. 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. Enterprise is explicit, optional, and fail-closed before remote operations. It does not auto-create a PR; `create-pr` is an explicit user-triggered recorder. Merge and issue closure remain human-controlled.

## Lifecycle and recovery

All lifecycle CLI commands use `--json --contract 3`:

- `pocketto-pi lifecycle transition <spec_dir> <event-type> --artifact <root>:<kind>:<relative-path>:<sha256> --json --contract 3` commits local state and one durable event.
- `pocketto-pi lifecycle drain <spec_dir> --json --contract 3` replays pending events in revision order without creating events.
- `pocketto-pi lifecycle repair <spec_dir> --json --contract 3` repairs lifecycle-owned projection fields only when task state is recoverable; otherwise it fails closed without changing state.
- `pocketto-pi lifecycle migrate <spec_dir> --from v3 --json --contract 3` explicitly migrates only a pristine v3 plan with no execution progress.

A progressed or non-pristine v3 plan returns `PIN_V3_REQUIRED` unchanged and must finish with the v3 CLI/Enterprise pair. v3 progress is never silently converted. A v4 preflight warns for v3 installations; an unchanged v3 binary cannot warn about a future release. Mixed-major Enterprise installs fail closed while Core remains usable and pending v4 events are retained.

For rollback, disable or remove the Enterprise adapter but retain Core, `lifecycle.json`, `.pocket-meta.json`, `log.json`, pending events, and remote markers. Local execution continues. Pin a faulty adapter to the last compatible v4 release, correct it, then replay the same event IDs with `lifecycle drain`; do not automatically downgrade or destructively convert v4 state.

## Skills

### Pipeline
- [pocket-pitching](skills/pocket-pitching/SKILL.md): explore an unformed idea.
- [pocket-grinding](skills/pocket-grinding/SKILL.md): discover requirements and produce a spec.
- [pocket-planning](skills/pocket-planning/SKILL.md): create a TDD execution plan.
- [pocket-structuring](skills/pocket-structuring/SKILL.md): split plans into task packets.
- [pocket-development](skills/pocket-development/SKILL.md): execute tasks with audits and lifecycle events.
- [pocket-closing](skills/pocket-closing/SKILL.md): reconcile verdicts and close local plan state.

### Standalone
- [pocket-help](skills/pocket-help/SKILL.md): route users through the skills.
- [pocket-init](skills/pocket-init/SKILL.md): onboard a project; Enterprise remains opt-in.
- [create-pr](skills/create-pr/SKILL.md): explicit Enterprise PR recorder.
- [bug-hunting](skills/bug-hunting/SKILL.md): diagnose and fix confirmed bugs.
- [hotfix](skills/hotfix/SKILL.md): small-to-medium changes.
- [brand-design](skills/brand-design/SKILL.md): create a brand-aware design system.
- [structured-research](skills/structured-research/SKILL.md): validate an assumption with evidence.

## Enterprise references
- [Lifecycle contract](skills/pocket-enterprise/references/lifecycle-contract.md)
- [Issue reconciliation](skills/pocket-enterprise/references/issue-reconciliation.md)
- [Phase and closure reconciliation](skills/pocket-enterprise/references/phase-reconciliation.md)
- [Full README](README.md)
- [Changelog](CHANGELOG.md)