pocket-init git:20261007.a2a1e61A

Immutable. This exact content never changes and is served at /api/v1/blob/2ec354a00d21a6d3.

---
name: pocket-init
description: Onboards an existing project onto Pocket by scanning its local configuration and writing a merge-safe project guide. Trigger on "pocket-init", "set up pocket", "onboard this project", or "generate AGENTS.md".
---

# Pocket Init

Standalone local onboarding. Takes an existing project from zero Pocket context to a useful project guide that the agent can rely on.

**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 or regenerating a stale project guide.

**Do NOT use when:** The project already has a current memory file. 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. **Local onboarding only** — inspect local project files and do not configure integrations or access remote services.
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 manifest scripts or local CI workflow files. 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, test file naming, and commit style visible in `git log --oneline -10`.
5. **Existing memory files** — check for `CLAUDE.md` and `AGENTS.md`. Note which exist and whether they already contain a `pocket-init` managed section.

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

## 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: Completion report

```text
POCKET_INIT_COMPLETE
Memory file : <memory_file> (created | merged)
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. |
| "I'll run a remote setup command while onboarding" | **STOP.** This skill performs local inspection and writes only the managed guide section. |
| "I'll write both CLAUDE.md and AGENTS.md to be safe" | One memory file per project. Two copies drift apart. |