Pocket Init

Standalone local onboarding. Takes an existing project from zero Pocket context to a useful project guide that the agent can rely on, and optionally enables Pocket Education with a persisted learner profile.

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 Education for a learner.

Do NOT use when: The project already has a current memory file and the learner profile it wants. To change learner levels later, use

pocket-education

(it never needs a re-init). 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 `` … `` managed section may be created or replaced. Everything outside it is untouched, byte for byte. The separately consented Education Gate writes only its learner profile through `edu`. 2. **Local onboarding only** — inspect local project files and do not configure integrations or access remote services. 3. **Evidence-based guide** — every build, test, lint, or typecheck command written to the memory file must come from an inspected manifest, config, or local CI workflow. Never infer a command from the stack. 4. **Education is opt-in and learner-owned** — never calibrate or write a `## Pocket Education` block unless the user says yes at the Education Gate, and never write levels the learner has not confirmed. An existing profile is reused, never recalibrated, unless the learner explicitly asks. </HARD-GATE>

Step 1: Brownfield scan (read-only)

Inspect the project before writing anything:

Stack & manifests —
```
package.json
```
,
```
pyproject.toml
```
,
```
Cargo.toml
```
,
```
go.mod
```
,
```
pom.xml
```
, or equivalent: language, package manager, declared scripts.
Commands — extract build / test / lint / typecheck commands from manifest scripts, project config, or local CI workflow files. Record each command verbatim with its source. If a command is not declared in the inspected files, write
```
Not configured
```
rather than guessing.
Layout — top-level directories and what lives in each (source, tests, docs, tooling). Keep it to the directories that matter.
Conventions — formatter/linter configs, test file naming, and commit style visible in
```
git log --oneline -10
```
.
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 Education
```
heading.

Briefly report the findings, then continue to Step 2 and write the guide. Do not wait for confirmation unless Step 2 cannot determine which memory file to use. The Education Gate in Step 4 controls only whether to create or resume an Education profile; declining it does not cancel the requested project guide.

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
```
.
If both files exist, use the file for the active platform and leave the other untouched. Ask the user only when the active platform or authoritative file is genuinely unclear, or when they request a specific target. 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: `<verified command | Not configured>`
- Test: `<verified command | Not configured>`
- Lint: `<verified command | Not configured>`
- Typecheck: `<verified command | Not configured>`

### Layout
…

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

Merge rules:

File missing → create it with the managed section as its content.
File exists with no marker tokens → append the managed section at the end, preceded by one blank line.
File exists with exactly one complete marker pair → replace only the managed section, preserving all bytes outside it.
Any marker token is present, but there is not exactly one complete, correctly ordered pair → do not write. Report the malformed section and ask how the user wants it repaired; do not guess which content is managed.

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

The

## Pocket Education

block lives outside the managed section and is owned by

edu

. Regenerating the project guide never touches it and never resets a learner's calibration. Other user-owned configuration blocks also remain untouched.

Step 4: Education Gate (opt-in)

Check current state first:

bash

npx -y pocketto-pi edu --json --contract 3

```
data.education
```
is
```
true
```
→ a learner profile exists. Report it and do not recalibrate (only an explicit learner request triggers
```
pocket-education
```
's recalibration). Skip to Step 5.
```
data.source
```
set but
```
data.education
```
is
```
false
```
→ a paused profile exists. Ask whether to resume it (
```
edu set --education true
```
); do not recalibrate. Skip to Step 5.
An error (
```
EDU_CONFIG_INVALID
```
,
```
EDU_SCHEMA_UNSUPPORTED
```
) → report it; do not overwrite the block. Skip to Step 5.

Otherwise ask the user one question:

"Enable Pocket Education for this repo? It keeps implementation human-owned — the agent explains, reviews, and guides while you write the code — and stores a learner profile so guidance adapts across sessions. (yes/no)"

If no → skip to Step 5. Keep the project guide written in Step 3; do not create or change an Education profile.

If yes:

Run the lightweight calibration in
```
<skills_root>/pocket-education/references/calibration.md
```
, using the Step 1 scan to choose the stack skills. It is onboarding, not an exam.
Show the proposed profile; the learner confirms or edits every level.

Write it to the same memory file:

bash

npx -y pocketto-pi edu init --file <memory_file> --level <skill>=<level> [--level ...] [--teaching-mode socratic] [--journal false] --json --contract 3

Re-run
```
edu --json --contract 3
```
and confirm
```
education=true
```
before continuing.

Education makes no remote call and does not change optional adapter behavior.

Step 5: Completion report

text

POCKET_INIT_COMPLETE
Memory file : <memory_file> (created | merged)
Education   : enabled (<n> skills, teaching_mode=<mode>, journal=<on|off>) | reused existing profile | disabled
Next        : /pocketto:pocket-grinding "<your first feature>"
              (Education on → /pocketto:pocket-education "<your first task>")

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 and, with explicit consent, the local learner profile.
"I'll write both CLAUDE.md and AGENTS.md to be safe"	One memory file per project. Two copies drift apart.
"They're a beginner — I'll enable Education for them"	STOP. Education is opt-in at the gate.
"A profile exists, but a fresh calibration would be more accurate"	Reuse it. Recalibration is the learner's call, not yours.
"Their answers say testing is guided — I'll write that without asking"	Show the proposal. The learner confirms every level.

pocket-init

NPX Install

Tags

SKILL.md Content