pocket-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

独立的本地接入流程。让现有项目从完全没有 Pocket 上下文，转变为具备可供 Agent 依赖的实用项目指南，并可选启用 Pocket Education，同时持久化学习者档案。

**核心原则：**读取项目，绝不凭空猜测。写入 memory file 的每项陈述，都必须基于本次运行中实际检查过的文件。现有 memory file 中的用户内容绝不会被覆盖。

**适用场景：**在现有仓库中采用 Pocket、重新生成过时的项目指南，或为学习者启用 Pocket Education。

**不适用场景：**项目已经拥有当前有效的 memory file 和所需的学习者档案。以后更改学习者级别时，使用

pocket-education

（无需重新 init）。进行规格工作时，使用

pocket-grinding

。

Invocation

调用方式

text

/pocketto:pocket-init [<dir>]

<dir>

defaults to the repository root of the current working directory.

text

/pocketto:pocket-init [<dir>]

<dir>

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>

<HARD-GATE> 1. **只合并，绝不覆盖**——如果 memory file 已存在，则只能创建或替换 `` … `` 托管区块。其余内容必须逐字节保持不变。只有在用户另行同意后，Education Gate 才能通过 `edu` 写入学习者档案。 2. **仅限本地接入**——只检查本地项目文件，不配置集成，也不访问远程服务。 3. **基于证据的指南**——写入 memory file 的每条 build、test、lint 或 typecheck 命令，都必须来自实际检查过的 manifest、配置文件或本地 CI workflow。绝不能根据技术栈推断命令。 4. **Education 由学习者主动选择且归学习者所有**——除非用户在 Education Gate 明确同意，否则绝不能校准或写入 `## Pocket Education` 区块；也绝不能写入学习者尚未确认的级别。除非学习者明确提出要求，否则应复用现有档案，绝不重新校准。 </HARD-GATE>

Step 1: Brownfield scan (read-only)

第 1 步：存量项目扫描（只读）

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.

在写入任何内容前检查项目：

技术栈与 manifest——
```
package.json
```
、
```
pyproject.toml
```
、
```
Cargo.toml
```
、
```
go.mod
```
、
```
pom.xml
```
或同等文件：语言、包管理器、已声明的 scripts。
命令——从 manifest scripts、项目配置或本地 CI workflow 文件中提取 build / test / lint / typecheck 命令。逐字记录每条命令及其来源。如果命令未在检查过的文件中声明，则写入
```
Not configured
```
，不得猜测。
布局——顶层目录及其用途（源码、测试、文档、工具）。仅保留重要目录。
约定——formatter/linter 配置、测试文件命名方式，以及
```
git log --oneline -10
```
中可见的 commit 风格。
现有 memory file——检查
```
CLAUDE.md
```
和
```
AGENTS.md
```
。记录哪些文件存在，以及是否已包含
```
pocket-init
```
托管区块或
```
## Pocket Education
```
标题。

简要报告检查结果，然后继续执行第 2 步并写入指南。除非第 2 步无法确定应使用哪个 memory file，否则无需等待确认。第 4 步中的 Education Gate 只控制是否创建或恢复 Education 档案；拒绝启用不会取消已请求的项目指南。

Step 2: Pick the memory file

第 2 步：选择 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>

检测当前平台并选择目标文件：

以 Claude Code plugin/skill 形式运行 →
```
CLAUDE.md
```
。
在 Pi 下运行 →
```
AGENTS.md
```
。
如果两个文件都存在，则使用当前活动平台对应的文件，另一个保持不变。仅当活动平台或权威文件确实无法确定，或用户指定了目标文件时，才询问用户。绝不能同时写入两个文件。

将选择结果记录为

<memory_file>

。

Step 3: Write the managed section

第 3 步：写入托管区块

Compose the project guide from Step 1 findings:

markdown

<!-- pocket-init:start -->

根据第 1 步的检查结果编写项目指南：

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

Build:
```
<verified command | Not configured>
```
Test:
```
<verified command | Not configured>
```
Lint:
```
<verified command | Not configured>
```
Typecheck:
```
<verified command | Not configured>
```

Layout

…

Conventions

…


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.

…


合并规则：

- 文件不存在 → 创建文件，并将托管区块作为其内容。
- 文件存在但没有 marker token → 在文件末尾追加托管区块，并在其前保留一个空行。
- 文件存在且恰好包含一对完整 marker → 只替换托管区块，保留区块之外的所有字节。
- 存在任何 marker token，但并非恰好一对完整且顺序正确的 marker → 不进行写入。报告区块格式异常，并询问用户希望如何修复；不要猜测哪些内容属于托管范围。

区块应控制在约 60 行以内——memory file 是索引，而不是文档。

`## Pocket Education` 区块位于**托管区块之外**，归 `edu` 所有。重新生成项目指南绝不会修改该区块，也绝不会重置学习者的校准结果。其他由用户拥有的配置区块同样保持不变。

Step 4: Education Gate (opt-in)

第 4 步：Education Gate（主动选择）

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.

首先检查当前状态：

bash

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

```
data.education
```
为
```
true
```
→ 学习者档案已存在。报告现有档案并且不要重新校准（只有学习者明确提出请求时，才触发
```
pocket-education
```
的重新校准）。跳至第 5 步。
已设置
```
data.source
```
，但
```
data.education
```
为
```
false
```
→ 已存在暂停的档案。询问是否恢复（
```
edu set --education true
```
）；不要重新校准。跳至第 5 步。
出现错误（
```
EDU_CONFIG_INVALID
```
、
```
EDU_SCHEMA_UNSUPPORTED
```
）→ 报告错误；不要覆盖该区块。跳至第 5 步。

其他情况下只向用户询问一个问题：

"是否为该仓库启用 Pocket Education？它会让实现工作继续由人主导——Agent 负责解释、审查和引导，由你编写代码——并存储学习者档案，使指导能够跨会话适应。（是/否）"

如果选择否 → 跳至第 5 步。 保留第 3 步中已写入的项目指南；不要创建或修改 Education 档案。

如果选择是：

按照
```
<skills_root>/pocket-education/references/calibration.md
```
中的说明运行轻量级校准，并使用第 1 步的扫描结果选择技术栈技能。这是一次 onboarding，而不是考试。
展示建议的档案；学习者确认或编辑每一个级别。

将其写入同一个 memory file：

bash

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

重新运行
```
edu --json --contract 3
```
，确认
```
education=true
```
后再继续。

Education 不会发起远程调用，也不会改变可选 adapter 的行为。

Step 5: Completion report

第 5 步：完成报告

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>")

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.

想法	应对方式
"memory file 很乱——我要重写它"	停止。只有托管区块归你管理，其他所有内容都归用户所有。
"这是 Node 项目，测试命令 probably 是 `npm test` "	读取 manifest。只写入实际存在的命令。
"我会在 onboarding 期间运行远程设置命令"	停止。此 skill 仅执行本地检查，只写入托管指南区块，并且仅在明确同意后写入本地学习者档案。
"为了保险，我会同时写入 CLAUDE.md 和 AGENTS.md"	每个项目只能使用一个 memory file。两份副本会产生偏差。
"他们是初学者——我要为他们启用 Education"	停止。 Education 必须在 Gate 处由用户主动选择。
"档案已存在，但全新校准会更准确"	复用现有档案。是否重新校准由学习者决定，而不是你。
"他们的回答表明测试由人工指导——我不询问就写入"	先展示方案。每个级别都必须由学习者确认。