Pocket init

Pocket Init

Standalone onboarding skill. Takes an existing project from zero Pocket context to ready-to-run: a project memory file the agent can rely on, and — only when the user opts in — Pocket Enterprise mode with GitHub templates.

Core principle: Read the project, never guess it. Every claim written to the memory file must come from files actually inspected in this run. User content in an existing memory file is never overwritten.

Use this when: Adopting Pocket in an existing repo, regenerating a stale project guide, or enabling Pocket Enterprise for a team.

Do NOT use when: The project already has a current memory file and enterprise config — there is nothing to initialize. For spec work, go to pocket-grinding.

---

Invocation

/pocketto:pocket-init [<dir>]

<dir> defaults to the repository root of the current working directory.

---

Hard Constraints

<HARD-GATE> 1. **Merge, never clobber** — if the memory file exists, only the `<!-- pocket-init:start -->` … `<!-- pocket-init:end -->` managed section may be created or replaced. Everything outside it is untouched, byte for byte. 2. **Enterprise is opt-in** — never enable enterprise mode, call `gh`, or write `.github/` files unless the user explicitly says yes at the Enterprise Gate below. 3. **Evidence-based guide** — every command written to the memory file (build, test, lint) must be read from a manifest or config file, not assumed from the stack. </HARD-GATE>

---

Step 1: Brownfield scan (read-only)

Inspect the project before writing anything:

1. Stack & manifests — package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, or equivalent: language, package manager, declared scripts.
2. Commands — extract the real build / test / lint / typecheck commands from the manifest scripts or CI workflows (.github/workflows/*). Record them verbatim.
3. Layout — top-level directories and what lives in each (source, tests, docs, tooling). Keep it to the directories that matter.
4. Conventions — formatter/linter configs, commit style visible in git log --oneline -10, test file naming.
5. Existing memory files — check for CLAUDE.md and AGENTS.md. Note which exist and whether they already contain a pocket-init managed section or a ## Pocket Enterprise heading.

Summarize the findings to the user in a few lines before writing.

Step 2: Pick the memory file

Detect the platform and choose the target:

• Running as a Claude Code plugin/skill → CLAUDE.md.
• Running under Pi → AGENTS.md.
• Ambiguous, or both files already exist → ask the user which file to use. Never write both.

Record the choice as <memory_file>; it is also the --file value for mode init in Step 4.

Step 3: Write the managed section

Compose the project guide from Step 1 findings:

<!-- pocket-init:start -->
## Project Guide (generated by pocket-init)

### Stack
…

### Commands
- Build: `…`
- Test: `…`
- Lint: `…`

### Layout
…

### Conventions
…
<!-- pocket-init:end -->

Merge rules:

• File missing → create it with the managed section as its content.
• File exists, no markers → append the managed section at the end, preceded by one blank line.
• File exists with markers → replace only the content between (and including) the markers.

Keep the section under ~60 lines — a memory file is an index, not documentation.

Step 4: Enterprise Gate (opt-in)

Check current state first:

npx -y pocketto-pi mode --json --contract 2

If data.enterprise is already true → report the active config and skip to Step 5 (offer scaffolding only if .github templates are missing).

Otherwise ask the user one question:

"Enable Pocket Enterprise for this repo? It links specs to GitHub issues, opens PRs per phase, and posts review verdicts to the PR. Requires the gh CLI. (yes/no)"

If no → stop here. Emit the final report (Step 6) without any GitHub call. Fail-closed, identical to every other enterprise-aware skill.

If yes:

1. Prerequisites (skill layer — the CLI does not call gh):
   • gh auth status — not authenticated → STOP with an actionable gh auth login error.
   • git remote get-url origin — no remote → STOP with an actionable error.
2. Ask whether merges should require an approved PR review (require_approval) — default no.
3. Initialize:

   npx -y pocketto-pi mode init --enterprise true --branch-strategy branch --create-pr true [--require-approval true] --file <memory_file> --json --contract 2
   

4. Re-run mode preflight and confirm enterprise=true before continuing.

Step 5: GitHub scaffolding (enterprise only)

npx -y pocketto-pi scaffold github --json --contract 2

Report data.wrote and data.skipped (existing templates are never overwritten). Then ensure the label exists:

gh label create pocket-plan --description "Tracked through the Pocket pipeline" --color 1D76DB

If the label already exists, gh errors — treat that as success and continue.

Step 6: Completion report

POCKET_INIT_COMPLETE
Memory file : <memory_file> (created | merged)
Enterprise  : enabled (branch, create_pr=true, require_approval=<bool>) | disabled
Scaffold    : .github/ISSUE_TEMPLATE/pocket-plan.md, .github/pull_request_template.md | skipped
Next        : /pocketto:pocket-grinding "<your first feature>"

---

Red Flags

Thought	Counter
"The memory file is messy — I'll rewrite it"	STOP. Only the managed section is yours. Everything else is user content.
"It's a Node project, tests are probably npm test"	Read the manifest. Write only commands that actually exist.
"Enterprise would help this team — I'll enable it"	STOP. Enterprise is opt-in at the gate. No yes, no gh, no .github/ writes.
"Templates exist but look wrong — overwrite them"	scaffold github never overwrites; report the skip and let the user decide.
"I'll write both CLAUDE.md and AGENTS.md to be safe"	One memory file per project. Two copies drift apart.