Pocket Init

---
name: pocket-init
description: Onboards an existing (brownfield) project onto Pocket. Scans the codebase and writes a project memory file (CLAUDE.md or AGENTS.md), optionally enables Pocket Enterprise (mode init) and scaffolds GitHub issue/PR templates. Trigger on "pocket-init", "set up pocket", "onboard this project", "generate CLAUDE.md", "enable enterprise mode".
---

# 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

```text
/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:

```markdown
<!-- 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:

```bash
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:
   ```bash
   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)

```bash
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:

```bash
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

```text
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. |